Golang SDK (#166)

* Init Golang SDK * search table * examples contrinued * delete snippets * Add python sdk schema edit references (#167) * add python sdk schema edit references * Update 040-SDK/020-Python/020-examples.mdx Co-authored-by: Philip Krauss <[email protected]> * Update 040-SDK/020-Python/020-examples.mdx Co-authored-by: Philip Krauss <[email protected]> * Update 040-SDK/020-Python/020-examples.mdx Co-authored-by: Philip Krauss <[email protected]> * Update 040-SDK/020-Python/020-examples.mdx Co-authored-by: Philip Krauss <[email protected]> * Update 040-SDK/020-Python/020-examples.mdx Co-authored-by: Philip Krauss <[email protected]> * Update 020-examples.mdx --------- Co-authored-by: Philip Krauss <[email protected]> * Point GH actions to FE (#168) * fix missing commas (#169) * Fix pricing docs URL (#170) rate limiting URL was pointing to an old docs page. * add updates for api docs (#165) * add updates for api docs * rewording * Update 060-Rest-API/010-authentication.mdx Co-authored-by: Kostas Botsas <[email protected]> * Update 060-Rest-API/020-contexts.mdx Co-authored-by: Kostas Botsas <[email protected]> * Update 010-authentication.mdx * links * update lint * update heading * update heading --------- Co-authored-by: Kostas Botsas <[email protected]> * Vercel deploys via github action (#173) * clarify Postman Bearer Token (#175) * clarify Postman Bearer Token * Update 060-Rest-API/020-contexts.mdx Co-authored-by: joan-ing <[email protected]> * reword * Update preview.yml * Update preview.yml --------- Co-authored-by: joan-ing <[email protected]> Co-authored-by: Alexis Rico <[email protected]> * Update sparse-checkout in workflows (#176) * Clarify main branch in Workflow (#178) * Clarify main used in Workflow * Update 040-workflow.mdx reword * Update 040-workflow.mdx reword 2 * Update docs for search change (#177) Signed-off-by: Alexis Rico <[email protected]> * more create examples * replace tabs with spaces * align var names * fix bulk insert example * one more * linting * update samples * one more update example * vector search examples * ask samples * trx snippet * update numeric ops * overview page * change alert to warning * Update 040-SDK/030-Go/010-overview.mdx Co-authored-by: joan-ing <[email protected]> * Update 040-SDK/030-Go/010-overview.mdx Co-authored-by: joan-ing <[email protected]> * Update 020-Getting-started/040-workflow.mdx Co-authored-by: joan-ing <[email protected]> * Update 020-Getting-started/040-workflow.mdx Co-authored-by: joan-ing <[email protected]> * Update 020-Getting-started/040-workflow.mdx Co-authored-by: joan-ing <[email protected]> * Update 040-SDK/020-Python/020-examples.mdx Co-authored-by: joan-ing <[email protected]> * add search items * Update 040-SDK/030-Go/010-overview.mdx Co-authored-by: joan-ing <[email protected]> * make linter happy * Update 040-SDK/030-Go/010-overview.mdx Co-authored-by: joan-ing <[email protected]> * Apply suggestions from code review Co-authored-by: joan-ing <[email protected]> * indent * add search skel * indent * add response struct * linter * Apply suggestions from code review Co-authored-by: joan-ing <[email protected]> * add install --------- Signed-off-by: Alexis Rico <[email protected]> Co-authored-by: Kostas Botsas <[email protected]> Co-authored-by: Dave Snider <[email protected]> Co-authored-by: joan-ing <[email protected]> Co-authored-by: Richard Gill <[email protected]> Co-authored-by: Alexis Rico <[email protected]>
xataio · Dec 6, 2023 · edf0a00 · edf0a00
1 parent a48b8a4
commit edf0a00
Show file tree

Hide file tree

Showing 11 changed files with 770 additions and 129 deletions.
diff --git a/020-Getting-started/040-workflow.mdx b/020-Getting-started/040-workflow.mdx
@@ -162,11 +162,11 @@ xata pull my_feature
 
 On completion, notice Xata updated our client files in `src/xata.ts` and added migration files in the `.xata/migrations` folder. The later files are needed for GitHub to pick up on the changes we've made. Each time you make changes to your database branch, you will need to run `xata pull my_feature`.
 
-### Commit your code, and create a GitHub PR
+### Commit code and create a pull request
 
-Once you are happy with your changes you should commit your files and create a GitHub PR for your Git branch. Xata's GitHub application will look for new files in your `.xata/migrations` folder so make sure they are included in the commit. Regardless of whether migrations are present, Xata will generate a preview branch for any PR you deploy using a `preview-{branch_name}` naming system. This is done by forking the `main` branch, applying schema migrations from the Pull Request branch and copying over sample data from `main` (excluding file attachments). The Xata app bot will leave a comment with the details.
+Once you are happy with your changes you should commit your files and create a GitHub pull request for your Git branch. Xata's GitHub application will look for new files in your `.xata/migrations` folder so make sure they are included in the commit. Regardless of whether migrations are present, Xata will generate a preview branch for any pull request you deploy using a `preview-{branch_name}` naming system. This is done by forking the `main` branch, applying schema migrations from the pull request branch and copying over sample data from `main` (excluding file attachments). The Xata app bot will leave a comment with the details.
 
-If you also have Vercel or Netlify configured for your repository you should see their bot make a similar comment. As long as your integrations were set up properly, the preview deployment that your host provides should be using the preview database that Xata provides. The workflow should be the same whether you are using the Netlify of Vercel integration.
+If you also have Vercel or Netlify configured for your repository, you should see their bot make a similar comment. As long as your integrations were set up properly, the preview deployment that your host provides should use the preview database that Xata provides. The workflow should be the same whether you are using the Netlify of Vercel integration.
 
 ![Xata bot on GitHub](images/xata-bot.png)
 

diff --git a/040-SDK/020-Python/020-examples.mdx b/040-SDK/020-Python/020-examples.mdx
@@ -486,7 +486,7 @@ print(to_rfc339(date_with_tz, tz_europe_vienna))
 
 The Xata SDK provides schema editing operations under the [Table](https://xata-py.readthedocs.io/en/latest/api.html#xata.api.table.Table) class.
 
-You can create tables, add and delete columns, or set the full table schema at once.
+You can create tables, add and delete columns, or set the full table schema.
 
 ```python
 from xata.client import XataClient

diff --git a/040-SDK/030-Go/010-overview.mdx b/040-SDK/030-Go/010-overview.mdx
@@ -0,0 +1,75 @@
+---
+title: Xata SDK for Go
+navTitle: SDK overview
+keywords: ['go', 'golang', 'sdk']
+description: Get to know Xata using Go
+slug: sdk/go/overview
+published: true
+---
+
+<Alert status="warning">
+  The Go SDK is currently in *alpha*. This means that it does not include all endpoints and is subject to potential
+  breaking changes before reaching its `1.0.0` stable General Availability (GA) release.
+</Alert>
+
+The Go SDK is available on GitHub: https://github.com/xataio/xata-go
+
+## Install
+
+```bash
+go get github.com/xataio/xata-go@latest
+```
+
+## Configuration
+
+The client needs a `XATA_API_KEY` environment variables for authentication and the `.xatarc` file for the database URL. Refer to [our installation guide](/docs/getting-started/installation#xatarc) to initialize your project with the `.xatarc` file.
+
+## Example
+
+After setting up your project and adding Xata credentials, create an example Go file.
+
+The following example code demonstrates using the SDK to connect to Xata, retrieve a list of workspaces, and then print out details of the first workspace in the list.
+
+In your text editor, paste the following code into your `example.go` file and save the file:
+
+```go
+package main
+
+import (
+  "context"
+  "fmt"
+
+  "github.com/xataio/xata-go/xata"
+)
+
+func main() {
+  workspaces, _ := xata.NewWorkspacesClient()
+  resp, _ := workspaces.List(context.TODO())
+  fmt.Printf("%#v\n", *resp.Workspaces[0])
+}
+```
+
+In the terminal, enter `go run .` to run the code.
+
+The code snippet calls `workspaces.List(ctx)` API to list all workspaces and prints the details of the first workspace with `fmt.Printf("%#v\n", *resp.Workspaces[0])`.
+
+### Runnable Example
+
+You can run the snippet from above on your machine by, pulling the example code from the xataio/xata-go repository
+
+```bash
+wget -O example.go "https://raw.githubusercontent.com/xataio/xata-go/main/examples/list_workspaces.go"
+go mod edit -module=example.com/mod
+go mod download github.com/xataio/xata-go@main
+```
+
+Run the code with the command:
+
+```bash
+XATA_API_KEY="<INSERT_YOUR_API_KEY>" go run example.go
+```
+
+## Known Limitations
+
+- [Numeric operations](/docs/sdk/update#numeric-operations) are currently not supported using the update API. As a workaround, you can use the transaction API [example](/docs/sdk/transaction).
+- Not all Xata endpoints are available at the alpha state of the SDK. You can check the coverage [here](https://github.com/xataio/xata-go/issues/1).
diff --git a/040-SDK/101-get.mdx b/040-SDK/101-get.mdx
@@ -9,19 +9,19 @@ published: true
 
 The general form of a query is:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 
 ```ts
 import { getXataClient } from "./xata";
 
 const client = getXataClient();
 const data = await client
-.db[table]
-.select([...])
-.filter({ ... })
-.sort({ ... })
-.page({ ... })
-.getMany();
+  .db[table]
+  .select([...])
+  .filter({ ... })
+  .sort({ ... })
+  .page({ ... })
+  .getMany();
 ```
 
 ```python
@@ -38,6 +38,26 @@ data = xata.data().query("{table_name}", {
     ...
   },
   "page": {
+    ...
+  }
+})
+```
+
+```go
+searchClient, _ := xata.NewSearchAndFilterClient()
+data, _ := searchClient.Query(context.TODO(), xata.QueryTableRequest{
+  TableName: "{tabel_name}",
+  Payload: xata.QueryTableRequestPayload{
+		Columns: []string{"col_1", ".."},
+    Filter: &xata.FilterExpression{
+			// ..
+		},
+    Sort: xata.NewSortExpressionFromStringSortOrderMapList(
+			// ..
+    ),
+    Page: &xata.SearchPageConfig{
+      // ..
+		},
   }
 })
 ```
@@ -62,6 +82,7 @@ data = xata.data().query("{table_name}", {
     ...
   },
   "page": {
+    ...
   }
 }
 ```
@@ -72,7 +93,7 @@ For the REST API example, note that a POST request is used, even though the data
 
 All the requests are optional, so the simplest query request looks like this:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 
 ```ts
 const teams = await xata.db.Teams.getMany();
@@ -82,6 +103,13 @@ const teams = await xata.db.Teams.getMany();
 teams = xata.data().query("Teams")
 ```
 
+```go
+client, _ := xata.NewSearchAndFilterClient()
+teams, _ := data.Query(context.TODO(), xata.QueryTableRequest{
+  TableName: "Teams",
+})
+```
+
 ```jsonc
 // POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
 
@@ -98,7 +126,7 @@ teams = xata.data().query("Teams")
 
 The response looks like this:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 ```ts
 [
   {
@@ -112,26 +140,32 @@ The response looks like this:
 ```
 
 ```python
-  "records": [
-    {
-      "id": "rec_c8hng2h26un90p8sr7k0",
-      "name": "Matrix",
-      "owner": {
-        "id": "myid"
-      },
-      "xata": {
-        "version": 0,
-        "createdAt": "2023-05-15T08:21:31.96526+01:00",
-        "updatedAt": "2023-05-15T21:58:54.072595+01:00"
-      }
-    }
-  ],
-  "meta": {
-    "page": {
-      "cursor": "jMq7DcIwEIDhnjH-2sWRAsItAT2KkOU8bAgB3Zkqyu6IDei_",
-      "more": false
+"records": [
+  {
+    "id": "rec_c8hng2h26un90p8sr7k0",
+    "name": "Matrix",
+    "owner": {
+      "id": "myid"
+    },
+    "xata": {
+      "version": 0,
+      "createdAt": "2023-05-15T08:21:31.96526+01:00",
+      "updatedAt": "2023-05-15T21:58:54.072595+01:00"
     }
   }
+],
+"meta": {
+  "page": {
+    "cursor": "jMq7DcIwEIDhnjH-2sWRAsItAT2KkOU8bAgB3Zkqyu6IDei_",
+    "more": false
+  }
+}
+```
+
+```go
+// type QueryTableResponse
+Meta    *RecordsMetadata
+Records []*Record
 ```
 
 ```json
@@ -226,7 +260,7 @@ Unless there's a specific reason to prefer another method, getMany() is generall
 
 You can retrieve a record with a given ID using a request like this:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 
 ```ts
 const user = await xata.db.Users.read('myid');
@@ -236,6 +270,17 @@ const user = await xata.db.Users.read('myid');
 user = xata.records().get("Users", "myid")
 ```
 
+```go
+client, _ := xata.NewRecordsClient()
+user, _ := client.Get(context.TODO(), xata.GetRecordRequest{
+  RecordRequest: xata.RecordRequest{
+    DatabaseName: xata.String("{db}"),
+    TableName:    "Users",
+  },
+  RecordID: "myid",
+})
+```
+
 ```jsonc
 // POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
 
@@ -257,7 +302,7 @@ By default, the Query API returns all columns of the queried table. For link col
 
 For example, if you are only interested in the name and the city of the user, you can make a request like this:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 
 ```ts
 const users = await xata.db.Users.select(['name', 'city']).getMany();
@@ -269,6 +314,16 @@ users = xata.data().query("Users", {
 })
 ```
 
+```go
+client, err := xata.NewSearchAndFilterClient()
+users, _ := client.Query(context.TODO(), xata.QueryTableRequest{
+  TableName: "Users",
+  Payload: xata.QueryTableRequestPayload{
+    Columns: []string{"name", "city"},
+  },
+})
+```
+
 ```jsonc
 // POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
 
@@ -310,7 +365,7 @@ It's worth noting that the special columns [id](/docs/concepts/data-model#id), [
 
 The same syntax can be used to select columns from a linked table, therefore adding new columns to the response. For example, to query all the columns of the teams table and also add all the columns of the owner user, you can use:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 
 ```ts
 const teams = await xata.db.Teams.select(['*', 'owner.*']).getMany();
@@ -322,6 +377,16 @@ users = xata.data().query("Users", {
 })
 ```
 
+```go
+client, err := xata.NewSearchAndFilterClient()
+users, _ := client.Query(context.TODO(), xata.QueryTableRequest{
+  TableName: "Users",
+  Payload: xata.QueryTableRequestPayload{
+    Columns: []string{"*", "owner.*"},
+  },
+})
+```
+
 ```jsonc
 // POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
 
@@ -341,7 +406,7 @@ users = xata.data().query("Users", {
 
 You can do this transitively as well, for example:
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 ```ts
 const posts = await xata.db.Posts.select([
   "title",
@@ -360,6 +425,20 @@ posts = xata.data().query("Posts", {
 })
 ```
 
+```go
+client, err := xata.NewSearchAndFilterClient()
+users, _ := client.Query(context.TODO(), xata.QueryTableRequest{
+  TableName: "Users",
+  Payload: xata.QueryTableRequestPayload{
+    Columns: []string{
+      "title",
+      "author.*",
+      "author.team.*",
+    },
+  },
+})
+```
+
 ```jsonc
 // POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql
 
@@ -382,7 +461,7 @@ In this example, the `author` is a link column from `Posts` to `Users` and `team
 
 By default, when retrieving a record by its ID, only the ID column of linked records is included in the response. However, you have the option to request the linked columns to be expanded. In the following examples, the code is using the `.read()` method to retrieve a record with the ID `myid` from the `Posts` table. The code specifies it wants the `author` column to be expanded and to retrieve more information from the `author` linked record.
 
-<TabbedCode tabs={['TypeScript', 'Python', 'SQL', 'JSON']}>
+<TabbedCode tabs={['TypeScript', 'Python', 'Go', 'SQL', 'JSON']}>
 
 ```ts
 const user = await xata.db.Posts.read('myid', ['author.*']);
@@ -392,6 +471,18 @@ const user = await xata.db.Posts.read('myid', ['author.*']);
 user = xata.records().get("Posts", "myid", columns=["author.*"])
 ```
 
+```go
+client, _ := xata.NewRecordsClient()
+record, _ := client.Get(context.TODO(), xata.GetRecordRequest{
+    RecordRequest: xata.RecordRequest{
+      DatabaseName: xata.String("{db}"),
+      TableName:    "Users",
+    },
+    RecordID: "myid",
+    Columns:  []string{"author.*"},
+  })
+```
+
 ```jsonc
 // POST https://{workspace}.{region}.xata.sh/db/{db}:{branch}/sql