xataio / xata-go Goto Github PK

Document how to add a new client or a method to the SDK

Add comments similar to Python SDK to all Public API items.

Please add the following operations to the Transaction tests:

• insert
• update
• get

https://github.com/xataio/xata-go/blob/main/xata/records_client_test.go#L487

We should be able to generate fern code via make target

In the workspace scope spec, there are 2 cases where types are referencing themselves recursively

      description: Object column value
      type: object
      additionalProperties:
        anyOf:
          - type: string
          - type: boolean
          - type: number
          - type: array
            items:
              type: string
          - type: array
            items:
              type: number
          - $ref: '#/components/schemas/DateTime'
          - $ref: '#/components/schemas/ObjectValue'

and

    ProjectionConfig:
      description: A structured projection that allows for some configuration.
      type: object
      properties:
        name:
          description: >-
            The name of the column to project or a reverse link specification,
            see [API
            Guide](https://xata.io/docs/concepts/data-model#links-and-relations).
          type: string
        columns:
          $ref: '#/components/schemas/QueryColumnsProjection'

...

    QueryColumnsProjection:
      type: array
      items:
        oneOf:
          - type: string
          - $ref: '#/components/schemas/ProjectionConfig'

@philkra clarified that

• ObjectValue is going to be deprecated => manually removed from specs
• ProjectionConfig => QueryColumnsProjection => ProjectionConfig => This has a legitimate use case. We'll deal with that later. Currently we removed the reference from QueryColumnsProjection manually.

Please add the following headers to the client:

• x-xata-agent: client=GO_SDK; version=0.0.1 (space, and no trailing ;)
• user-agent: xataio/xata-go:0.0.1

0.0.1 should be a const named SDK_VERSION

follow up on new feature, ref: xataio/mdx-docs#197

also make MediaType and Name of type string

type InputFile struct {
	// Base64 encoded content
	Base64Content *string `json:"base64Content,omitempty"`
	// Enable public access to the file
	EnablePublicUrl *bool      `json:"enablePublicUrl,omitempty"`
	MediaType       *MediaType `json:"mediaType,omitempty"`
	Name            FileName   `json:"name"`
	// Time to live for signed URLs
	SignedUrlTimeout *int `json:"signedUrlTimeout,omitempty"`
}

file[] is a string type enum for the column types.
This is breaking the code generator.
We should manually handle this before code generation.

Rename file[] to fileMap in the yaml api spec generated by fern.

This section has a get request with a request body.
This won't allow fern code generator to run.
Since this section is deprecated, we should comment out/delete this section before generating code.

Fern SDK cannot read the record data (no schema) from the API response.
We had to change the type to map[string]interface when talking to API and put it in a structured type where we provide the record id, meta data and record data as a map[string]interface type.

We had to manualy update the generated type:

package api

type Record map[string]interface{}

Post processing the auto-gen code:

• Delete record.go and insert_record_response.go
• Create a new file with the following content:

type Record map[string]interface{}

type InsertRecordResponse map[string]interface{}

Similar issues also exists for:

• bulk insert table records response
• update record with id response
• insert record with id response
• upsert recort with id response
• record
• files client
• records client
• get file response
• transaction success results item

Endpoints

• Files (all, 6 endpoints)
• Records (remaining 6 endpoints)
• Search and Filter (all, 8 endpoints)
• #11

Tasks

• make target for codegen

Out of scope (Endpoints)

Reference: #1
Milestone 4 (ms4): #6

• Authentication (all)
• Branch (all - ms4)
• Databases (all - ms4)
• Invites (all)
• Migrations (all)
• OAuth (all)
• Table (all - ms4)
• User (all - ms4)
• Workspace (all - ms4)

The Columns attributes of the Column type is defined as an array of Column type (recursive). It's purpose is defining the returning columns in the response. It should be a type of array of strings where the array elements representing the column names.
Ref: https://xata.io/docs/api-reference/db/db_branch_name/tables/table_name/columns#create-new-column

Numeric operations require one more level in the payload for update request, example.

The following operation can not be executed.

// PATCH https://{workspace}.{region}.xata.sh/db/{db}:{branch}/tables/{table}/data/{record_id}
 
{
  "counter": {
    "$increment": 1
  }
}

resp, err := records.Update(context.TODO(), xata.UpdateRecordRequest{
	RecordRequest: xata.RecordRequest{
		TableName: "Users",
	},
	RecordID: "myid2",
	Body: map[string]*xata.DataInputRecordValue{
		"counter": xata.ValueFromString("{$increment: 10}"),
	},
})

I tried optimistically the above, but failed (surprise 😄 )

Please add a method ValueFromNumericOperations that models the key value pair.

xata.ValueFromNumericOperations("$increment", 10)

At the moment we allow clients to be created with optional ClientOptions, but we do not support all available options.

We should also add:

• WorkspaceID
• Branch
• Region

• list branches: GET /dbs/{db_name}
• get branch details: GET /db/{db_branch_name}
• create branch: PUT /db/{db_branch_name}
• delete a branch: DELETE /db/{db_branch_name}
• list databases: GET /workspaces/{workspace_id}/dbs
• rename a database: POST /workspaces/{workspace_id}/dbs/{db_name}/rename
• get workspace: GET /workspaces/{workspace_id}
• update workspace: PUT /workspaces/{workspace_id}
• get current user: GET /user
• get table schema: GET /db/{db_branch_name}/tables/{table_name}/schema
• get table columns: GET /db/{db_branch_name}/tables/{table_name}/columns

Authentication

• GET /user/keys
• POST /user/keys/{key_name}
• DELETE /user/keys/{key_name}

Branch

type BranchClient interface {
  List(ctx context.Context, dbName string) (*xatagenworkspace.ListBranchesResponse, error)
  GetDetails(ctx context.Context, request BranchRequest) (*xatagenworkspace.DbBranch, error)
  Create(ctx context.Context, request CreateBranchRequest) (*xatagenworkspace.CreateBranchResponse, error)
  Delete(ctx context.Context, request BranchRequest) (*xatagenworkspace.DeleteBranchResponse, error)
}

• GET /dbs/{db_name}
• GET /db/{db_branch_name}
• PUT /db/{db_branch_name}
• DELETE /db/{db_branch_name}
• GET /db/{db_branch_name}/metadata
• PUT /db/{db_branch_name}/metadata
• GET /db/{db_branch_name}/stats
• GET /dbs/{db_name}/gitBranches
• POST /dbs/{db_name}/gitBranches
• DELETE /dbs/{db_name}/gitBranches
• GET /dbs/{db_name}/resolveBranch

Databases

type DatabasesClient interface {
  Create(ctx context.Context, request CreateDatabaseRequest) (*xatagencore.CreateDatabaseResponse, error)
  Delete(ctx context.Context, request DeleteDatabaseRequest) (*xatagencore.DeleteDatabaseResponse, error)
  GetRegions(ctx context.Context) (*xatagencore.ListRegionsResponse, error)
  GetRegionsWithWorkspaceID(ctx context.Context, workspaceID string) (*xatagencore.ListRegionsResponse, error)
  List(ctx context.Context) (*xatagencore.ListDatabasesResponse, error)
  ListWithWorkspaceID(ctx context.Context, workspaceID string) (*xatagencore.ListDatabasesResponse, error)
  Rename(ctx context.Context, request RenameDatabaseRequest) (*xatagencore.DatabaseMetadata, error)
}

• GET /workspaces/{workspace_id}/dbs
• GET /workspaces/{workspace_id}/dbs/{db_name}
• PUT /workspaces/{workspace_id}/dbs/{db_name}
• DELETE /workspaces/{workspace_id}/dbs/{db_name}
• PATCH /workspaces/{workspace_id}/dbs/{db_name}
• POST /workspaces/{workspace_id}/dbs/{db_name}/rename
• GET /workspaces/{workspace_id}/regions

Files

type FilesClient interface {
  GetItem(ctx context.Context, request GetFileItemRequest) (*xatagenworkspace.GetFileResponse, error)
  PutItem(ctx context.Context, request PutFileItemRequest) (*xatagenworkspace.FileResponse, error)
  DeleteItem(ctx context.Context, request DeleteFileItemRequest) (*xatagenworkspace.FileResponse, error)
  Get(ctx context.Context, request GetFileRequest) (*xatagenworkspace.GetFileResponse, error)
  Put(ctx context.Context, request PutFileRequest) (*xatagenworkspace.FileResponse, error)
  Delete(ctx context.Context, request DeleteFileRequest) (*xatagenworkspace.FileResponse, error)
}

• GET /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file/{file_id}
• PUT /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file/{file_id}
• DELETE /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file/{file_id}
• GET /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file
• PUT /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file
• DELETE /db/{db_branch_name}/tables/{table_name}/data/{record_id}/column/{column_name}/file

Invites

• POST /workspaces/{workspace_id}/invites
• DELETE /workspaces/{workspace_id}/invites/{invite_id}
• PATCH /workspaces/{workspace_id}/invites/{invite_id}
• POST /workspaces/{workspace_id}/invites/{invite_key}/accept
• POST /workspaces/{workspace_id}/invites/{invite_id}/resend

Migrations

• GET /db/{db_branch_name}/migrations
• POST /db/{db_branch_name}/migrations/plan
• POST /db/{db_branch_name}/migrations/execute
• POST /db/{db_branch_name}/schema/history
• POST /db/{db_branch_name}/schema/compare
• POST /db/{db_branch_name}/schema/compare/{branch_name}
• POST /db/{db_branch_name}/schema/update
• POST /db/{db_branch_name}/schema/preview
• POST /db/{db_branch_name}/schema/apply
• POST /db/{db_branch_name}/schema/push

OAuth

• GET /user/oauth/clients
• DELETE /user/oauth/clients/{client_id}
• GET /user/oauth/tokens
• DELETE /user/oauth/tokens/{token}
• PATCH /user/oauth/tokens/{token}

Records

type RecordsClient interface {
  Transaction(ctx context.Context, request TransactionRequest) (*xatagenworkspace.TransactionSuccess, error)
  Insert(ctx context.Context, request InsertRecordRequest) (*Record, error)
  BulkInsert(ctx context.Context, request BulkInsertRecordRequest) ([]*Record, error)
  Update(ctx context.Context, request UpdateRecordRequest) (*Record, error)
  Upsert(ctx context.Context, request UpsertRecordRequest) (*Record, error)
  InsertWithID(ctx context.Context, request InsertRecordWithIDRequest) (*Record, error)
  Get(ctx context.Context, request GetRecordRequest) (*Record, error)
  Delete(ctx context.Context, request DeleteRecordRequest) error
}

• POST /db/{db_branch_name}/transaction
• POST /db/{db_branch_name}/tables/{table_name}/data
• GET /db/{db_branch_name}/tables/{table_name}/data/{record_id}
• PUT /db/{db_branch_name}/tables/{table_name}/data/{record_id}
• POST /db/{db_branch_name}/tables/{table_name}/data/{record_id}
• DELETE /db/{db_branch_name}/tables/{table_name}/data/{record_id}
• PATCH /db/{db_branch_name}/tables/{table_name}/data/{record_id}
• POST /db/{db_branch_name}/tables/{table_name}/bulk

Search And Filter

type SearchAndFilterClient interface {
  Query(ctx context.Context, request QueryTableRequest) (*xatagenworkspace.QueryTableResponse, error)
  SearchBranch(ctx context.Context, request SearchBranchRequest) (*xatagenworkspace.SearchBranchResponse, error)
  SearchTable(ctx context.Context, request SearchTableRequest) (*xatagenworkspace.SearchTableResponse, error)
  VectorSearch(ctx context.Context, request VectorSearchTableRequest) (*xatagenworkspace.VectorSearchTableResponse, error)
  Ask(ctx context.Context, request AskTableRequest) (*xatagenworkspace.AskTableResponse, error)
  AskFollowUp(ctx context.Context, request AskFollowUpRequest) (*xatagenworkspace.AskTableSessionResponse, error)
  Summarize(ctx context.Context, request SummarizeTableRequest) (*xatagenworkspace.SummarizeTableResponse, error)
  Aggregate(ctx context.Context, request AggregateTableRequest) (*xatagenworkspace.AggregateTableResponse, error)
}

• POST /db/{db_branch_name}/tables/{table_name}/query
• POST /db/{db_branch_name}/search
• POST /db/{db_branch_name}/tables/{table_name}/search
• POST /db/{db_branch_name}/tables/{table_name}/vectorSearch
• POST /db/{db_branch_name}/tables/{table_name}/ask
• POST /db/{db_branch_name}/tables/{table_name}/ask/{session_id}
• POST /db/{db_branch_name}/tables/{table_name}/summarize
• POST /db/{db_branch_name}/tables/{table_name}/aggregate

SQL

• POST /db/{db_branch_name}/sql

Table

type TableClient interface {
  Create(ctx context.Context, request TableRequest) (*xatagenworkspace.CreateTableResponse, error)
  Delete(ctx context.Context, request TableRequest) (*xatagenworkspace.DeleteTableResponse, error)
  AddColumn(ctx context.Context, request AddColumnRequest) (*xatagenworkspace.AddTableColumnResponse, error)
  DeleteColumn(ctx context.Context, request DeleteColumnRequest) (*xatagenworkspace.DeleteColumnResponse, error)
  GetSchema(ctx context.Context, request TableRequest) (*xatagenworkspace.GetTableSchemaResponse, error)
  GetColumns(ctx context.Context, request TableRequest) (*xatagenworkspace.GetTableColumnsResponse, error)
}

• PUT /db/{db_branch_name}/tables/{table_name}
• DELETE /db/{db_branch_name}/tables/{table_name}
• PATCH /db/{db_branch_name}/tables/{table_name}
• GET /db/{db_branch_name}/tables/{table_name}/schema
• PUT /db/{db_branch_name}/tables/{table_name}/schema
• GET /db/{db_branch_name}/tables/{table_name}/columns
• POST /db/{db_branch_name}/tables/{table_name}/columns
• GET /db/{db_branch_name}/tables/{table_name}/columns/{column_name}
• DELETE /db/{db_branch_name}/tables/{table_name}/columns/{column_name}
• PATCH /db/{db_branch_name}/tables/{table_name}/columns/{column_name}

User

type UsersClient interface {
  Get(ctx context.Context) (*xatagencore.UserWithId, error)
}

• GET /user
• PUT /user
• DELETE /user

Workspaces

type WorkspacesClient interface {
  List(ctx context.Context) (*xatagencore.GetWorkspacesListResponse, error)
  Create(ctx context.Context, request *WorkspaceMeta) (*xatagencore.Workspace, error)
  Delete(ctx context.Context, workspaceID string) error
  Get(ctx context.Context) (*xatagencore.Workspace, error)
  GetWithWorkspaceID(ctx context.Context, workspaceID string) (*xatagencore.Workspace, error)
  Update(ctx context.Context, request UpdateWorkspaceRequest) (*xatagencore.Workspace, error)
}

• GET /workspaces
• POST /workspaces
• GET /workspaces/{workspace_id}
• PUT /workspaces/{workspace_id}
• DELETE /workspaces/{workspace_id}
• GET /workspaces/{workspace_id}/members
• PUT /workspaces/{workspace_id}/members/{user_id}
• DELETE /workspaces/{workspace_id}/members/{user_id}

The Fern code generator requires an account to use.
We should create one for the repo.
Currently we are using a personal one.
See here.

Right now, it looks like the only way to build a AggExpressionTopValues is with NewTopValuesAggExpression, which expects a TopValuesAgg.

However, the latter doesn't accept any other aggregation (only column name and size), in contrast to the underlying TopValuesAgg. Thus, it's not possible to perform a query like:

{
  "aggs": {
    "topOpenings": {
      "topValues": {
        "column": "opening",
        "size": 5,
        "aggs": {
          "winRatio": {
            "average": {
              "column": "win",
            },
          }
        }
      }
    }
  }
}

Any plans? ETA? Thanks!

I would even be happy to contribute with the minimum viable set of changes to make the exposed TopValuesAgg type to be equals (or point to) the internal one. However, I could understand that you may want to revisit that internal/external types divergence in a wider and/or more generic way.

Resolve milestone 3.