scopedb

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

README

ScopeDB SDK for Go

Version Docs CI License

The official Go client for ScopeDB. Run ScopeQL queries, browse the catalog, and write rows with bounded asynchronous streams. For application writes, start with Table.AppendStream.

Install

Requires Go 1.27.3 or later. Use the SDK in a trusted server-side process and keep API keys out of source control.

From your application module:

go get github.com/scopedb/goscopedb@latest

Run a query

Set SCOPEDB_ENDPOINT and SCOPEDB_API_KEY using the connection guide. Save this program as main.go and run go run .:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	scopedb "github.com/scopedb/goscopedb"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	client, err := scopedb.NewClient(scopedb.Config{
		Endpoint: os.Getenv("SCOPEDB_ENDPOINT"),
		APIKey:   os.Getenv("SCOPEDB_API_KEY"),
	})
	if err != nil {
		return err
	}
	defer client.Close()

	result, err := client.Query(context.Background(), "SELECT 1 AS ready")
	if err != nil {
		return err
	}
	rows, err := result.ToObjects()
	if err != nil {
		return err
	}
	fmt.Println(rows)
	return nil
}

Query waits for the result. ToObjects returns rows keyed by column name; integers retain their full int64/uint64 precision. See result conversion for other representations.

Write rows

Inside run, using the client above and an existing events table with id int and name string columns:

ctx := context.Background()
stream, err := client.Table("events").AppendStream(scopedb.AppendStreamOptions{})
if err != nil {
	return err
}
if err := stream.Send(ctx, map[string]any{"id": 1, "name": "page_view"}); err != nil {
	_, _ = stream.Shutdown(context.WithoutCancel(ctx))
	return err
}
report, err := stream.Shutdown(ctx)
if err != nil {
	return err
}
fmt.Println("written rows:", report.CommittedRows)

Send queues a row; Shutdown waits for pending writes and closes the stream. Use Flush to wait while keeping it open. If you already have NDJSON, use Table.AppendNDJSON.

Find what you need

Task Documentation
Query, manage schemas, or write rows Usage guide
Encode rows and tune delivery Write contracts
Configure timeouts and HTTP Client configuration
Diagnose failures and recover Error handling
Run complete programs Examples
Upgrade an application Release notes and migration guides

The API reference describes individual types and methods. For ScopeQL syntax, see the query guide and language reference. Report problems through GitHub issues.

Contribute

See the contribution guide for development setup and checks.

License

Licensed under the Apache License, Version 2.0.

Documentation

Overview

Package scopedb provides a Go client for ScopeDB queries, catalog management, and table writes.

Create and reuse a Client with NewClient. Client.Query submits a ScopeQL statement and waits for a ResultSet. For detached execution, retain a StatementHandle from Statement.Submit to inspect, wait for, or cancel it. A local context deadline does not cancel the remote statement.

Client.Catalog selects complete definitions at tenant, database, schema, table, or view scope. Apply replaces the selected subtree; omitted fields are cleared. Use CatalogOptions for dry runs, version preconditions, and explicit destructive-change authorization.

Table.AppendStream batches Go structs or maps with bounded backpressure. Send confirms local admission; Flush and Shutdown return delivery reports. Always settle accepted rows with Shutdown, including after a producer error. Table.AppendNDJSON sends one caller-encoded request without SDK retries. Client.Close releases idle connections and does not shut down streams.

Inspect Error for server diagnostics and operation outcomes. An ambiguous write may have committed; retryability alone does not make replay safe. See AppendRetryOptions and AppendDeliveryReport for stream recovery rules.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrAppendStreamFull means TrySend could not reserve bounded local capacity.
	ErrAppendStreamFull = errors.New("append stream buffer is full")
	// ErrAppendStreamClosed means the stream no longer accepts rows.
	ErrAppendStreamClosed = errors.New("append stream is closed")
	// ErrAppendRetryExhausted means the configured retry count or elapsed budget
	// ended. The wrapped append error still describes the last attempt.
	ErrAppendRetryExhausted = errors.New("append retry budget exhausted")
	// ErrAppendRowInvalid means a row did not encode to one JSON object.
	ErrAppendRowInvalid = errors.New("append row must encode to a JSON object")
	// ErrAppendRowTooLarge means one encoded row exceeds the append stream request limit.
	ErrAppendRowTooLarge = errors.New("append row exceeds the protocol limit")
)
View Source
var ErrResponseTooLarge = errors.New("response body exceeds the 64 KiB limit")

ErrResponseTooLarge means an HTTP error body or Append acknowledgement exceeded the 64 KiB read limit. The oversized body is not retained.

View Source
var ErrStatementCancelled = errors.New("statement was cancelled")

ErrStatementCancelled means the server confirmed cancellation. It is distinct from context.Canceled, which only describes a local request or wait.

Functions

This section is empty.

Types

type AppendDeliveryOutcome

type AppendDeliveryOutcome uint8

AppendDeliveryOutcome summarizes one completed delivery barrier.

const (
	// AppendDeliverySucceeded means the interval settled without failed, ambiguous, or dropped rows.
	AppendDeliverySucceeded AppendDeliveryOutcome = iota
	// AppendDeliveryPartial means some rows committed and some did not settle cleanly.
	AppendDeliveryPartial
	// AppendDeliveryFailed means no rows committed and at least one row failed or dropped.
	AppendDeliveryFailed
	// AppendDeliveryAmbiguous means no rows are confirmed committed and at least one row may have committed.
	AppendDeliveryAmbiguous
)

func (AppendDeliveryOutcome) String

func (o AppendDeliveryOutcome) String() string

type AppendDeliveryReport

type AppendDeliveryReport struct {
	// Outcome summarizes delivery for this barrier interval.
	Outcome AppendDeliveryOutcome
	// AcceptedRows is the number of rows locally admitted in the interval.
	AcceptedRows uint64
	// CommittedRows is the number of rows confirmed committed.
	CommittedRows uint64
	// FailedRows is the number of rejected or unsent accepted rows.
	FailedRows uint64
	// AmbiguousRows is the number of rows whose commit outcome is unknown.
	AmbiguousRows uint64
	// DroppedRows is the number of TrySend calls rejected locally in the interval.
	DroppedRows      uint64
	CommittedBatches uint64
	FailedBatches    uint64
	AmbiguousBatches uint64
	Retries          uint64
	Duration         time.Duration
}

AppendDeliveryReport contains settlement counters since the previous barrier.

type AppendDroppedRows

type AppendDroppedRows struct {
	// BufferFull counts rows rejected because immediate local admission was unavailable.
	BufferFull uint64
	// InvalidRow counts values that did not encode to a JSON object.
	InvalidRow uint64
	// RowTooLarge counts values over the single-request protocol limit.
	RowTooLarge uint64
	// Closed counts attempts after shutdown or a terminal failure.
	Closed uint64
}

AppendDroppedRows contains lifetime TrySend failures by reason.

type AppendErrorDetails

type AppendErrorDetails struct {
	Status             AppendOutcome    `json:"status"`
	RowErrors          []AppendRowError `json:"row_errors"`
	RowErrorsTruncated bool             `json:"row_errors_truncated"`
}

AppendErrorDetails contains the structured outcome of a failed append.

type AppendFailurePolicy

type AppendFailurePolicy uint8

AppendFailurePolicy controls what a stream does after a remote batch fails.

const (
	// AppendFailureStop stops admission after the first failed batch.
	AppendFailureStop AppendFailurePolicy = iota
	// AppendFailureContinue accounts for the failed batch and processes later rows.
	AppendFailureContinue
)

func (AppendFailurePolicy) String

func (p AppendFailurePolicy) String() string

type AppendLastFailure

type AppendLastFailure struct {
	// At is when the client observed the failure.
	At time.Time
	// Message is the original error message.
	Message string
	// Code and Details preserve the last attempt's structured server error.
	Code    string
	Details json.RawMessage
	// Status is the aggregate rejected or unknown outcome across all attempts.
	Status AppendOutcome
	// HTTPStatus is zero when no HTTP response was available.
	HTTPStatus int
	// RequestID is the request identifier reported by the service, when present.
	RequestID string
	// RetryAfter is the service-provided retry delay, when present.
	RetryAfter time.Duration
	// Retryable reports the underlying error's conservative retry classification;
	// it is false for unknown outcomes. RetryAmbiguous may opt into replaying such
	// outcomes, so this field is not the stream's retry decision.
	Retryable bool
	// WriteDetails identifies a client timeout or cancellation, when present.
	WriteDetails *WriteErrorDetails
	// RowErrors preserves optional legacy row diagnostics; modern errors describe the whole request.
	RowErrors []AppendRowError
	// RowErrorsTruncated reports whether the service omitted additional row errors.
	RowErrorsTruncated bool
}

AppendLastFailure describes the last failed batch, including failures before dispatch. Status covers all attempts; other diagnostics describe the last one.

type AppendOutcome added in v0.8.0

type AppendOutcome string

AppendOutcome describes a write's commit outcome. Table append responses and client-side interruption details use these values. String values retain the historical JSON spellings committed, rejected, and unknown.

const (
	// AppendOutcomeSucceeded means all reported rows committed.
	AppendOutcomeSucceeded AppendOutcome = "committed"
	// AppendOutcomeFailed means no rows committed and the request is safe to correct and retry.
	AppendOutcomeFailed AppendOutcome = "rejected"
	// AppendOutcomeAmbiguous means the client cannot determine whether rows committed.
	AppendOutcomeAmbiguous AppendOutcome = "unknown"
)

type AppendRetryOptions added in v0.7.0

type AppendRetryOptions struct {
	MaxRetries int
	// RetryAmbiguous opts into retries after a transient failure that may have
	// committed. This can insert duplicate rows. It defaults to false and does
	// not override client timeouts, cancellation, server refusal, or the delivery budget.
	RetryAmbiguous bool
	// Zero durations use defaults: 100 ms initial, 5 s maximum backoff, 5 min
	// elapsed budget per dispatched batch (including HTTP attempts).
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	MaxElapsedTime time.Duration
}

AppendRetryOptions configures retries of an exact encoded batch for temporary HTTP 429 rejections and known-unsent temporary connection failures, with optional replay of transient ambiguous outcomes. A nil Retry uses the defaults; a non-nil option with MaxRetries=0 disables retries. Client timeouts and cancellations with ambiguous outcomes are never retried. Temporary connection failures known to precede dispatch can be retried safely.

type AppendRowError

type AppendRowError struct {
	RowIndex uint64 `json:"row_index"`
	Column   string `json:"column"`
	Message  string `json:"message"`
}

AppendRowError preserves optional legacy per-row diagnostics. Modern errors describe the whole request; do not parse messages to infer row outcomes.

type AppendRowsResult

type AppendRowsResult struct {
	Status          AppendOutcome `json:"status"`
	NumRowsInserted int64         `json:"num_rows_inserted"`
}

AppendRowsResult is the result of a committed table append.

type AppendStream

type AppendStream struct {
	// contains filtered or unexported fields
}

AppendStream asynchronously batches rows into bounded NDJSON append requests. Send and TrySend are safe to call from concurrent producer goroutines.

func (*AppendStream) Flush

Flush dispatches all rows admitted before this barrier and waits for settlement. Its report covers activity since the previous completed barrier. Continue mode may return a non-succeeded report without an error; callers must inspect Outcome. Canceling ctx stops only this wait; an already enqueued barrier keeps running. If ctx ends first, Flush returns a zero report and ctx.Err(). The barrier still advances the report interval when it completes; inspect lifetime Stats and Stats().LastReport to account for delivery after an interrupted wait.

func (*AppendStream) Send

func (s *AppendStream) Send(ctx context.Context, row any) error

Send serializes row with encoding/json and admits it, waiting for bounded local capacity. Row may be a typed struct or any other value that encodes as one top-level JSON object. Success does not validate the destination table schema or confirm a remote commit.

func (*AppendStream) Shutdown

Shutdown permanently closes admission and settles every admitted row. It is idempotent and returns the original final report on repeated calls. Continue mode may return a non-succeeded report without an error. Canceling ctx stops only the caller's wait. If ctx ends first, Shutdown returns a zero report and ctx.Err().

func (*AppendStream) Stats

func (s *AppendStream) Stats() AppendStreamStats

Stats returns a race-safe snapshot. Row and retry counters are lifetime totals and are not reset by Flush. LastFailure and LastReport are caller-owned copies; PendingRows, PendingBytes, and InFlightBatches are current gauges.

func (*AppendStream) TrySend

func (s *AppendStream) TrySend(row any) error

TrySend serializes row with encoding/json and attempts local admission without waiting for capacity. Row must encode as one top-level JSON object. Success does not validate the destination table schema or confirm a remote commit.

type AppendStreamOptions

type AppendStreamOptions struct {
	// FailurePolicy defaults to AppendFailureStop.
	FailurePolicy AppendFailurePolicy
	Retry         *AppendRetryOptions
	// TargetBatchBytes defaults to 4 MiB and cannot exceed the request limit.
	TargetBatchBytes int
	// MaxBatchRows defaults to 200,000 and cannot exceed the request limit.
	MaxBatchRows int
	// FlushInterval defaults to one second.
	FlushInterval time.Duration
	// MaxBufferedBytes bounds accepted encoded rows, including in-flight batches.
	// It defaults to 64 MiB and excludes temporary encoding/compression buffers
	// and rows held by blocked Send callers.
	MaxBufferedBytes int
	// MaxConcurrentBatches defaults to four, cannot exceed 1024, and may be set
	// to one for serial request submission.
	MaxConcurrentBatches int
	// AttemptTimeout bounds each HTTP attempt. Nil inherits Config.WriteTimeout.
	// A pointer to zero disables this limit, but the delivery/retry budget still applies.
	// Negative values are invalid. The value is copied when the stream is created.
	// A timeout after connection acquisition leaves the commit outcome unknown.
	AttemptTimeout *time.Duration
}

AppendStreamOptions configures bounded asynchronous table appends. Zero-valued fields use SDK defaults.

type AppendStreamState

type AppendStreamState uint8

AppendStreamState is the lifecycle state of an AppendStream.

const (
	// AppendStreamOpen means the stream accepts rows.
	AppendStreamOpen AppendStreamState = iota
	// AppendStreamClosing means shutdown has closed admission and is settling rows.
	AppendStreamClosing
	// AppendStreamClosed means shutdown settled all accepted rows without a fatal error.
	AppendStreamClosed
	// AppendStreamFailed means strict delivery stopped after a batch failure.
	AppendStreamFailed
)

func (AppendStreamState) String

func (s AppendStreamState) String() string

type AppendStreamStats

type AppendStreamStats struct {
	// State is the current stream lifecycle state.
	State           AppendStreamState
	AcceptedRows    uint64
	CommittedRows   uint64
	FailedRows      uint64
	AmbiguousRows   uint64
	DroppedRows     uint64
	DroppedByReason AppendDroppedRows
	Retries         uint64
	PendingRows     uint64
	PendingBytes    int
	InFlightBatches int
	// LastFailure is nil until a batch fails.
	LastFailure *AppendLastFailure
	// LastReport is nil until a delivery barrier completes.
	LastReport *AppendDeliveryReport
}

AppendStreamStats is a race-safe lifetime snapshot.

type Catalog added in v0.7.0

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog manages the complete user catalog of a tenant and selects individual resources.

func (*Catalog) Apply added in v0.7.0

func (c *Catalog) Apply(ctx context.Context, definition *CatalogDocument, options ...CatalogOptions) (CatalogResult[*CatalogDocument], error)

Apply replaces the complete tenant catalog. An empty document clears the tenant. Options may be omitted; by default, changes apply without a version precondition and potentially destructive changes are rejected.

func (*Catalog) Database added in v0.7.0

func (c *Catalog) Database(database string) *CatalogResource[*CatalogDatabase]

Database selects a database and its complete subtree.

func (*Catalog) Get added in v0.7.0

Get returns the complete tenant definition and its opaque version.

func (*Catalog) Raw added in v0.7.0

Raw selects the tenant catalog as JSON, preserving fields unknown to this SDK.

func (*Catalog) Schema added in v0.7.0

func (c *Catalog) Schema(database, schema string) *CatalogResource[*CatalogSchema]

Schema selects a schema and its tables and views.

func (*Catalog) Table added in v0.7.0

func (c *Catalog) Table(database, schema, table string) *CatalogResource[*CatalogTable]

Table selects a complete table definition.

func (*Catalog) View added in v0.7.0

func (c *Catalog) View(database, schema, view string) *CatalogResource[*CatalogView]

View selects a view definition.

type CatalogColumn added in v0.7.0

type CatalogColumn struct {
	Name       string               `json:"name"`
	DataType   DataType             `json:"data_type"`
	Expression *string              `json:"expression,omitempty"`
	Comment    *string              `json:"comment,omitempty"`
	Indexes    []CatalogColumnIndex `json:"indexes,omitempty"`
}

CatalogColumn defines a stored or computed column and its additional indexes.

type CatalogColumnIndex added in v0.7.0

type CatalogColumnIndex struct {
	Type     string `json:"type"`
	Analyzer string `json:"analyzer,omitempty"`
}

CatalogColumnIndex defines an additional column index. Only Type "search" is supported. Analyzer defaults to "log".

type CatalogDatabase added in v0.7.0

type CatalogDatabase struct {
	Name    string          `json:"name"`
	Comment *string         `json:"comment,omitempty"`
	Schemas []CatalogSchema `json:"schemas,omitempty"`
}

CatalogDatabase defines a database and its schemas.

type CatalogDistinct added in v0.7.0

type CatalogDistinct struct {
	On []string `json:"on,omitempty"`
	By []string `json:"by,omitempty"`
}

CatalogDistinct defines a table's distinct keys and ordering expressions.

type CatalogDocument added in v0.7.0

type CatalogDocument struct {
	Databases []CatalogDatabase `json:"databases,omitempty"`
}

CatalogDocument defines the complete user catalog of a tenant.

type CatalogMutationOutcome added in v0.8.0

type CatalogMutationOutcome string

CatalogMutationOutcome describes whether a failed Catalog mutation committed.

const (
	// CatalogMutationRejected means the server rejected the mutation.
	CatalogMutationRejected CatalogMutationOutcome = "rejected"
	// CatalogMutationUnknown means the mutation may have committed.
	CatalogMutationUnknown CatalogMutationOutcome = "unknown"
)

type CatalogOptions added in v0.7.0

type CatalogOptions struct {
	DryRun           bool
	AllowDestructive bool
	// ExpectedVersion is optional. Use Version from Get or a dry run to reject concurrent tenant catalog changes.
	// Preserve the token including quotes. Stale versions fail with HTTP 412 and precondition_failed.
	ExpectedVersion string
}

CatalogOptions controls preview, concurrent updates, and data-loss authorization. Apply and Delete accept zero or one options value.

type CatalogResource added in v0.7.0

type CatalogResource[T any] struct {
	// contains filtered or unexported fields
}

CatalogResource manages a selected catalog definition. Obtain one through the Catalog resource selectors; T is a definition pointer, or json.RawMessage for Raw.

func (*CatalogResource[T]) Apply added in v0.7.0

func (c *CatalogResource[T]) Apply(ctx context.Context, definition T, options ...CatalogOptions) (CatalogResult[T], error)

Apply replaces the resource with definition. Omitted fields and objects are cleared. With no options, changes apply without a version precondition and potentially destructive changes are rejected. DryRun validates and rolls back. Catalog writes are never automatically retried.

func (*CatalogResource[T]) Delete added in v0.7.0

func (c *CatalogResource[T]) Delete(ctx context.Context, options ...CatalogOptions) (CatalogResult[T], error)

Delete removes a single database, schema, table, or view. With no options, potentially destructive changes are rejected.

func (*CatalogResource[T]) Get added in v0.7.0

func (c *CatalogResource[T]) Get(ctx context.Context) (CatalogSnapshot[T], error)

Get returns a complete definition, without pagination. Typed definitions reject unknown fields to prevent lossy read-modify-write cycles; use Raw to retain them.

func (*CatalogResource[T]) Raw added in v0.7.0

Raw selects the same resource as JSON, preserving fields unknown to this SDK.

type CatalogResult added in v0.7.0

type CatalogResult[T any] struct {
	Before      T    `json:"before"`
	After       T    `json:"after"`
	Destructive bool `json:"destructive"`
	// Version is the base tenant catalog version for a dry run, or the resulting version after a write.
	Version string `json:"-"`
}

CatalogResult contains the normalized states compared in one server transaction. Typed definitions are nil when absent; Raw resources represent absence as JSON null.

type CatalogSchema added in v0.7.0

type CatalogSchema struct {
	Name    string         `json:"name"`
	Comment *string        `json:"comment,omitempty"`
	Tables  []CatalogTable `json:"tables,omitempty"`
	Views   []CatalogView  `json:"views,omitempty"`
}

CatalogSchema defines a schema, including its tables and views.

type CatalogSnapshot added in v0.7.0

type CatalogSnapshot[T any] struct {
	Definition T
	// Version is an opaque token for the whole tenant catalog, including its quotes.
	Version string
}

CatalogSnapshot contains a complete resource definition and its opaque version.

type CatalogTable added in v0.7.0

type CatalogTable struct {
	Name          string          `json:"name"`
	Comment       *string         `json:"comment,omitempty"`
	Columns       []CatalogColumn `json:"columns,omitempty"`
	PartitionBy   []string        `json:"partition_by,omitempty"`
	ClusterBy     []string        `json:"cluster_by,omitempty"`
	Distinct      CatalogDistinct `json:"distinct"`
	RetentionDays *int32          `json:"retention_days,omitempty"`
	Storage       json.RawMessage `json:"storage,omitempty"`
}

CatalogTable defines a table. Omitted collections are empty; omitted optional fields are cleared. Storage is accepted at creation and omitted from exports.

type CatalogView added in v0.7.0

type CatalogView struct {
	Name      string  `json:"name"`
	Statement string  `json:"statement"`
	Comment   *string `json:"comment,omitempty"`
}

CatalogView defines a view.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides access to ScopeDB APIs and is safe for concurrent use. Reuse a client to share its HTTP connection pool.

func NewClient

func NewClient(config Config) (*Client, error)

NewClient creates a new ScopeDB client with the given configuration.

func (*Client) Catalog added in v0.7.0

func (c *Client) Catalog() *Catalog

Catalog selects the complete tenant catalog. Names passed to its resource selectors are unescaped database, schema, table, or view names.

func (*Client) Close

func (c *Client) Close()

Close releases idle connections owned by the client. It does not close a caller-provided HTTP client.

func (*Client) Query

func (c *Client) Query(ctx context.Context, scopeql string) (*ResultSet, error)

Query submits a ScopeQL statement and waits for all result rows. A context error stops local waiting without cancelling server execution. Error.StatementID can be used to resume waiting on the same execution. Use Statement.Submit and retain its handle for explicit lifecycle management.

func (*Client) Statement

func (c *Client) Statement(stmt string) *Statement

Statement creates a new statement with the given ScopeQL statement.

func (*Client) StatementHandle

func (c *Client) StatementHandle(id uuid.UUID) *StatementHandle

StatementHandle creates a new StatementHandle with the given ID.

func (*Client) Table

func (c *Client) Table(tableName string) *Table

Table creates a new Table object with the given name.

type Compression

type Compression string

Compression defines the compression used for request bodies.

const (
	// CompressionZstd uses Zstandard compression.
	CompressionZstd Compression = "zstd"
	// CompressionGzip uses gzip compression.
	CompressionGzip Compression = "gzip"
)

type Config

type Config struct {
	// Endpoint is the URL of the ScopeDB service.
	Endpoint string `json:"endpoint"`
	// APIKey is the API key used for authentication.
	//
	// When provided, the client sends it as the Authorization header using the
	// Bearer scheme.
	APIKey string `json:"api_key"`
	// Compression controls Statement and Append request bodies, including direct
	// table appends and AppendStream batches. Catalog JSON is not compressed.
	//
	// The default is CompressionZstd. CompressionGzip is also supported.
	Compression Compression `json:"compression"`
	// WriteTimeout bounds each table append or catalog mutation request,
	// including reading its response body. Nil uses the default of 30 seconds;
	// a pointer to zero disables this limit. Negative values are invalid.
	// NewClient copies the value.
	// Caller context deadlines and HTTPClient timeouts still apply.
	// The budget starts after local encoding, compression, and request preparation.
	// Non-nil stream AttemptTimeout settings override this limit. A timeout after
	// dispatch leaves the commit outcome unknown; it does not roll back the write.
	WriteTimeout *time.Duration `json:"write_timeout"`
	// HTTPClient is the HTTP client used to send requests.
	//
	// When nil, the SDK creates and owns an independent HTTP client using Go's
	// default redirect policy. A supplied client retains its redirect policy,
	// remains owned by the caller, and is never closed by the SDK.
	HTTPClient *http.Client `json:"-"`
}

Config defines the configuration for the client.

type DataType

type DataType string

DataType is the type of field.

const (
	// StringDataType indicates the data is of string data type.
	StringDataType DataType = "string"
	// BinaryDataType indicates the data is of binary data type.
	BinaryDataType DataType = "binary"
	// IntDataType indicates the data is of int data type.
	IntDataType DataType = "int"
	// UIntDataType indicates the data is of uint data type.
	UIntDataType DataType = "uint"
	// FloatDataType indicates the data is of float data type.
	FloatDataType DataType = "float"
	// BooleanDataType indicates the data is of bool data type.
	BooleanDataType DataType = "boolean"
	// TimestampDataType indicates the data is of timestamp data type.
	TimestampDataType DataType = "timestamp"
	// IntervalDataType indicates the data is of interval data type.
	IntervalDataType DataType = "interval"
	// ArrayDataType indicates the data is of array data type.
	ArrayDataType DataType = "array"
	// ObjectDataType indicates the data is of object data type.
	ObjectDataType DataType = "object"
	// AnyDataType indicates the data is of any data type.
	AnyDataType DataType = "any"
	// NullDataType indicates the data is of null data type.
	NullDataType DataType = "null"
)

func (*DataType) UnmarshalJSON

func (d *DataType) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts canonical wire type names and rejects unsupported types.

type Error

type Error struct {
	// Details preserves code-specific HTTP or statement error information from the server.
	Details json.RawMessage
	Kind    ErrorKind
	// Code is the server error code, when provided, or an SDK outcome-unknown
	// code when a Statement submission could not be confirmed.
	// Unknown server codes are retained.
	Code       string
	Message    string
	HTTPStatus int
	RequestID  string
	RetryAfter time.Duration
	// ServerRetryable preserves the server hint independently of safe replay policy.
	// A valid false hint at either envelope level takes precedence over true,
	// even when other diagnostic fields are malformed.
	ServerRetryable *bool
	// CatalogOutcome is empty for reads, dry runs, and local validation failures.
	CatalogOutcome CatalogMutationOutcome
	// Retryable classifies temporary failures. After successful submission,
	// Query and Execute return false because replay would submit another statement.
	Retryable     bool
	AppendDetails *AppendErrorDetails
	// WriteDetails identifies a client or transport timeout or cancellation.
	// Outcome distinguishes an unsent append from a potentially committed write.
	// Existing error kinds, causes, and HTTP diagnostics remain available.
	WriteDetails *WriteErrorDetails
	// StatementID identifies the statement being submitted, inspected, or waited
	// for, when known. It does not prove acceptance or continued result retention.
	StatementID *uuid.UUID
	// StatementDetails contains the structured server failure for a failed
	// statement, when available.
	StatementDetails *StatementErrorDetails
	// contains filtered or unexported fields
}

Error represents a ScopeDB client or API error.

func (*Error) Error

func (e *Error) Error() string

Error returns the human-readable error message.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the transport, decoding, or configuration error that caused this error.

type ErrorKind

type ErrorKind string

ErrorKind identifies the operation-level category of a ScopeDB error.

const (
	// ErrorKindUnexpected is an error that has no more specific classification.
	ErrorKindUnexpected ErrorKind = "Unexpected"
	// ErrorKindConfigInvalid indicates invalid client configuration or arguments.
	ErrorKindConfigInvalid ErrorKind = "ConfigInvalid"
	// ErrorKindStatementFailed indicates a failed or cancelled statement.
	ErrorKindStatementFailed ErrorKind = "StatementFailed"
	// ErrorKindCatalogFailed indicates a catalog request failure or unknown commit outcome.
	ErrorKindCatalogFailed ErrorKind = "CatalogFailed"
	// ErrorKindAppendRowsFailed indicates a rejected append or an unknown commit outcome.
	ErrorKindAppendRowsFailed ErrorKind = "AppendRowsFailed"
)

type FieldSchema

type FieldSchema struct {
	// Name is the field name.
	Name string
	// Type is the field data type.
	Type DataType
}

FieldSchema describes a single field.

type ResultSet

type ResultSet struct {
	// TotalRows is the total number of rows in the result set.
	TotalRows uint64
	// Schema is the schema of the result set.
	Schema Schema
	// contains filtered or unexported fields
}

ResultSet stores the result of a statement execution.

func (*ResultSet) First

func (rs *ResultSet) First() (map[string]Value, bool, error)

First returns the first row keyed by column name. The boolean is false when the result set is empty.

func (*ResultSet) RawRows

func (rs *ResultSet) RawRows() ([][]*string, error)

RawRows returns the string-or-null cells from the JSON wire response without converting them to ScopeDB value types.

func (*ResultSet) ToObjects

func (rs *ResultSet) ToObjects() ([]map[string]Value, error)

ToObjects returns rows keyed by result column name.

Duplicate output column names are rejected because representing them as a map would silently discard values. Cell types follow ToValues.

func (*ResultSet) ToValues

func (rs *ResultSet) ToValues() ([][]Value, error)

ToValues returns rows as positional values. Signed and unsigned integers become int64 and uint64 without passing through floating point.

Binary cells are returned as []byte, timestamps as time.Time, and intervals as time.Duration. Array, object, and any cells remain JSON strings, while null cells are returned as nil. Conversion errors include the row and column.

type Schema

type Schema []*FieldSchema

Schema describes the columns of a query result.

type Statement

type Statement struct {

	// ID is an optional caller-provided statement ID.
	//
	// When nil, ScopeDB generates the statement ID.
	ID *uuid.UUID
	// MaxElapsed limits server-side time from submission, including queueing,
	// preparation, and execution. Polling does not reset it. Zero uses the
	// server default of one hour; negative durations are invalid.
	MaxElapsed time.Duration
	// contains filtered or unexported fields
}

Statement configures a ScopeQL statement before submission.

func (*Statement) Execute

func (s *Statement) Execute(ctx context.Context) (*ResultSet, error)

Execute submits the statement to ScopeDB for execution and waits for its completion. After submission, errors include Error.StatementID and are not marked retryable: use Client.StatementHandle with that ID to resume the existing execution.

func (*Statement) Submit

func (s *Statement) Submit(ctx context.Context) (*StatementHandle, error)

Submit submits the statement to ScopeDB for execution. A lost response does not prove rejection; set ID before submission when reconciliation needs a caller-known identifier.

type StatementErrorCode

type StatementErrorCode string

StatementErrorCode identifies the reason a statement failed. Unknown values are preserved for forward compatibility.

const (
	// StatementErrorCodeBadRequest indicates that the statement could not be
	// prepared or executed because of invalid input.
	StatementErrorCodeBadRequest StatementErrorCode = "bad_request"
	// StatementErrorCodeInternalServerError indicates an internal execution failure.
	StatementErrorCodeInternalServerError StatementErrorCode = "internal_server_error"
	// StatementErrorCodeTimeout indicates that the server-side time limit was
	// exceeded during queueing, preparation, or execution.
	StatementErrorCodeTimeout StatementErrorCode = "statement_timeout"
)

type StatementErrorDetails

type StatementErrorDetails struct {
	Code    StatementErrorCode `json:"code"`
	Message string             `json:"message"`
	Details json.RawMessage    `json:"details,omitempty"`
}

StatementErrorDetails contains the structured failure returned for a failed statement. Details is code-specific JSON and is nil when the server did not provide additional details.

type StatementHandle

type StatementHandle struct {
	// contains filtered or unexported fields
}

StatementHandle tracks a submitted statement. Its methods are safe to call concurrently, including Cancel while another goroutine is waiting. A handle must not be copied after first use.

func (*StatementHandle) Cancel

Cancel requests server cancellation and returns the complete observation. Completion may win the race: inspect Status, ResultSet, and Error. A cached terminal observation is returned without making another request and takes precedence over a failed in-flight cancellation request.

func (*StatementHandle) ID

func (h *StatementHandle) ID() uuid.UUID

ID returns the statement ID represented by this handle.

func (*StatementHandle) Refresh added in v0.7.0

Refresh fetches one complete observation. A cached terminal observation is returned without making another request. If a concurrent request caches a terminal observation, it also takes precedence over this request's failure. Other request failures leave the cache intact and retain their retry classification.

func (*StatementHandle) Snapshot added in v0.7.0

func (h *StatementHandle) Snapshot() *StatementSnapshot

Snapshot returns the latest local observation without making a request. It is nil until Submit, Refresh, or Cancel receives a response.

func (*StatementHandle) Wait

func (h *StatementHandle) Wait(ctx context.Context) (*ResultSet, error)

Wait polls until the statement is finished, failed, or cancelled.

A context error stops local waiting; it does not cancel the server statement. Use Cancel with a live context to request server cancellation. Terminal results remain cached even after the server expires its saved result.

type StatementProgress

type StatementProgress struct {
	// ComputeSeconds is cumulative server compute time, not elapsed wall time.
	ComputeSeconds float64 `json:"compute_seconds"`
	// TotalPercentage denotes the total progress in percentage: [0.0, 100.0].
	TotalPercentage float64 `json:"total_percentage"`
	// NanosFromSubmitted denotes the duration in nanoseconds since the statement is submitted.
	NanosFromSubmitted int64 `json:"nanos_from_submitted"`
	// NanosFromStarted denotes the duration in nanoseconds since the statement is started.
	NanosFromStarted int64 `json:"nanos_from_started"`
	// TotalStages denotes the total number of stages to execute.
	TotalStages int64 `json:"total_stages"`
	// TotalPartitions denotes the estimated total number of partitions to scan.
	TotalPartitions int64 `json:"total_partitions"`
	// TotalRows denotes the estimated total number of rows to scan.
	TotalRows int64 `json:"total_rows"`
	// TotalCompressedBytes denotes the estimated total number of compressed bytes to scan.
	TotalCompressedBytes int64 `json:"total_compressed_bytes"`
	// TotalUncompressedBytes denotes the estimated total number of uncompressed bytes to scan.
	TotalUncompressedBytes int64 `json:"total_uncompressed_bytes"`
	// ScannedStages denotes the total number of stages executed.
	ScannedStages int64 `json:"scanned_stages"`
	// ScannedPartitions denotes the number of partitions scanned.
	ScannedPartitions int64 `json:"scanned_partitions"`
	// ScannedRows denotes the number of rows scanned.
	ScannedRows int64 `json:"scanned_rows"`
	// ScannedCompressedBytes denotes the number of compressed bytes scanned.
	ScannedCompressedBytes int64 `json:"scanned_compressed_bytes"`
	// ScannedUncompressedBytes denotes the number of uncompressed bytes scanned.
	ScannedUncompressedBytes int64 `json:"scanned_uncompressed_bytes"`
	// SkippedPartitions denotes the number of partitions skipped by pruning.
	SkippedPartitions int64 `json:"skipped_partitions"`
	// SkippedRows denotes the number of rows skipped by pruning.
	SkippedRows int64 `json:"skipped_rows"`
	// SkippedCompressedBytes denotes the number of compressed bytes skipped by pruning.
	SkippedCompressedBytes int64 `json:"skipped_compressed_bytes"`
	// SkippedUncompressedBytes denotes the number of uncompressed bytes skipped by pruning.
	SkippedUncompressedBytes int64 `json:"skipped_uncompressed_bytes"`
}

StatementProgress is a struct that represents the progress of a statement.

type StatementSnapshot added in v0.7.0

type StatementSnapshot struct {
	ID        uuid.UUID
	CreatedAt time.Time
	Status    StatementStatus
	Progress  StatementProgress
	Error     *StatementErrorDetails
	ResultSet *ResultSet
}

StatementSnapshot is one observation of a statement. Error is present for a failed statement; ResultSet is present for a finished statement. Snapshots belong to the caller: modifying one does not change the handle's cache.

type StatementStatus

type StatementStatus string

StatementStatus is a string that represents the status of a statement.

const (
	// StatementStatusPending indicates the query is not started yet.
	StatementStatusPending StatementStatus = "pending"
	// StatementStatusRunning indicates the query is not finished yet.
	StatementStatusRunning StatementStatus = "running"
	// StatementStatusFinished indicates the query is finished.
	StatementStatusFinished StatementStatus = "finished"
	// StatementStatusFailed indicates the query is failed.
	StatementStatusFailed StatementStatus = "failed"
	// StatementStatusCancelled indicates the query is cancelled.
	StatementStatusCancelled StatementStatus = "cancelled"
)

func (StatementStatus) Terminated

func (s StatementStatus) Terminated() bool

Terminated returns true if the statement is finished, failed, or cancelled.

type Table

type Table struct {

	// Database is the database name. Empty uses "scopedb" for REST APIs.
	Database string
	// Schema is the schema name. Empty uses "public" for REST APIs.
	Schema string
	// Name is the name of the table.
	Name string
	// contains filtered or unexported fields
}

Table references a ScopeDB table.

func (*Table) AppendNDJSON

func (t *Table) AppendNDJSON(ctx context.Context, ndjson []byte) (AppendRowsResult, error)

AppendNDJSON sends one caller-encoded NDJSON request of at most 8 MiB uncompressed and 200,000 rows. The body contains one JSON object per non-empty line. It uses Config.Compression and Config.WriteTimeout and makes one SDK attempt without batching or retries. An error with an unknown commit outcome may follow a remote commit; inspect Error.AppendDetails before replaying.

Response bodies are limited to 64 KiB. Overflow returns an error matching ErrResponseTooLarge.

func (*Table) AppendStream

func (t *Table) AppendStream(options AppendStreamOptions) (*AppendStream, error)

AppendStream creates a bounded asynchronous append stream for this table.

func (*Table) Catalog added in v0.7.0

func (t *Table) Catalog() *CatalogResource[*CatalogTable]

Catalog selects this table's complete definition for Get, Apply, Delete, or Raw. The selector captures the current database, schema, and name.

func (*Table) Identifier

func (t *Table) Identifier() string

Identifier returns the quoted table identifier.

type Value

type Value any

Value stores the contents of a single cell from a ScopeDB statement result.

type WriteErrorDetails added in v0.7.0

type WriteErrorDetails struct {
	Reason  WriteErrorReason `json:"reason"`
	Outcome AppendOutcome    `json:"outcome"`
}

WriteErrorDetails describes an interrupted write. An unknown outcome may have committed; replay requires explicit acceptance of possible duplicates.

type WriteErrorReason added in v0.7.0

type WriteErrorReason string

WriteErrorReason identifies why a write attempt was interrupted.

const (
	// WriteErrorReasonTimeout means a client or transport deadline expired.
	WriteErrorReasonTimeout WriteErrorReason = "timeout"
	// WriteErrorReasonCancelled means the caller cancelled an in-flight write.
	WriteErrorReasonCancelled WriteErrorReason = "cancelled"
)

Directories

Path Synopsis
examples
append_ndjson command
Package main demonstrates one caller-encoded raw NDJSON table append.
Package main demonstrates one caller-encoded raw NDJSON table append.
append_stream command
Package main demonstrates strict bounded asynchronous table appends.
Package main demonstrates strict bounded asynchronous table appends.
catalog command
Package main demonstrates declarative catalog discovery.
Package main demonstrates declarative catalog discovery.
internal/exampleutil
Package exampleutil contains configuration shared by the runnable examples.
Package exampleutil contains configuration shared by the runnable examples.
patterns/bulk_append command
Package main imports NDJSON from standard input with bounded streaming writes.
Package main imports NDJSON from standard input with bounded streaming writes.
patterns/telemetry command
Package main demonstrates observable best-effort telemetry delivery.
Package main demonstrates observable best-effort telemetry delivery.
statement command
Package main demonstrates synchronous and asynchronous statement queries.
Package main demonstrates synchronous and asynchronous statement queries.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL