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 (source: 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.

• A key and your project id in NORBIX_API_KEY and NORBIX_PROJECT_ID — see Install a Norbix SDK. The key needs a role that may write records, for example Data Editor.

Install

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

Create the client

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.

	// 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.

	// 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:

	// 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

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.

• The same calls from the terminal: CLI.