> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/sdks/go-lang.md).

# Go

Write and read records from Go with the Norbix Go SDK.

The Go SDK is the module [`github.com/norbix-code/sdk-go/v2`](https://pkg.go.dev/github.com/norbix-code/sdk-go/v2) (source: [github.com/norbix-code/sdk-go](https://github.com/norbix-code/sdk-go)). It needs Go 1.22 or newer. Methods take the request as a `map[string]any` and decode the answer into any value you pass — a `map[string]any`, your own struct, or a generated type from `norbix/api/dtos`.

This page was run on 2026-10-06 with module version **v2.14.0** and Go 1.27. All the code below is one file, `main.go`: put the blocks one after the other.

## Before you start

* A project with a `books` collection — `title` (text, required), `pages` (number, required), `in_stock` (yes / no), `genre`. Create it in Cloud as in step 3 of the [Quickstart](/codemash/get-started/managed-service/quickstart.md).
* A key and your project id in `NORBIX_API_KEY` and `NORBIX_PROJECT_ID` — see [Install a Norbix SDK](/codemash/sdks/install.md). The key needs a role that may write records, for example **Data Editor**.

## Install

```sh
go mod init example.com/quickstart
go get github.com/norbix-code/sdk-go/v2
```

## Create the client

```go
package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"

	"github.com/norbix-code/sdk-go/v2/norbix"
	norbixerr "github.com/norbix-code/sdk-go/v2/norbix/errors"
)

func main() {
	// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
	c, err := norbix.New(norbix.Options{})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
	ctx := context.Background()
```

`c.API` is the data part (records, files, users), `c.Hub` the configuration part (schemas, integrations, templates). To pass the values in code instead: `norbix.Options{APIKey: "nbsu_…", ProjectID: "pr_…"}`.

## Write a record

A record goes in as a JSON string in `document`. The answer has the new record's `id`.

```go
	// Write: add one book to the `books` collection.
	doc, _ := json.Marshal(map[string]any{"title": "Dune", "pages": 412, "genre": "fiction"})
	var created struct{ ID string `json:"id"` }
	if err := c.API.Database.InsertOne(ctx, "books", map[string]any{"document": string(doc)}, &created); err != nil {
		log.Fatal(err)
	}
	fmt.Println("Inserted", created.ID)
```

## Read records

`Find` returns one page of records in `list.items`. Add `filter`, `sort` or `projection` to the request map as in [Search parameters](/codemash/cloud/concepts/search-parameters.md).

```go
	// Read: find the books.
	var found struct {
		List struct {
			Items []struct {
				Title string `json:"title"`
				Pages int    `json:"pages"`
			} `json:"items"`
		} `json:"list"`
	}
	if err := c.API.Database.Find(ctx, "books", map[string]any{"pageSize": 10}, &found); err != nil {
		log.Fatal(err)
	}
	for _, book := range found.List.Items {
		fmt.Printf("%s — %d pages\n", book.Title, book.Pages)
	}
```

## Handle errors

A failed call returns a `*norbixerr.Error` (or a typed variant: `AuthenticationError`, `NotFoundError`, `RateLimitError`, `ValidationError`) with the gateway's `Code` and `Message`, `HTTPStatus()`, and every error in `Errors`. Here the schema says `pages` is required:

```go
	// Error handling: the schema requires `pages`, so this insert fails.
	bad, _ := json.Marshal(map[string]any{"title": "Untitled draft"})
	err = c.API.Database.InsertOne(ctx, "books", map[string]any{"document": string(bad)}, nil)
	var e *norbixerr.Error
	if errors.As(err, &e) {
		fmt.Printf("Failed: %s — %s\n", e.Code, e.Message)
	}
}
```

## Run it

```sh
go run .
```

The output (the collection already had *The Hobbit*):

```
Inserted 6ac54bbf212c29912eaddd97
Dune — 412 pages
The Hobbit — 310 pages
Failed: CM-ERRORS-DATABASE-030 — Field 'pages' is invalid: a value is required
```

## Next steps

* Every operation, with a tab per language: [SDK reference](/codemash/sdks/database.md).
* The same calls from the terminal: [CLI](/codemash/cli/cli.md).