massengine

package module
v1.1.4 Latest Latest
Warning

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

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

README

MassEngine Go SDK (massengine-go)

Official zero-dependency Go client for MassEngine — the sub-5ms filtered vector search database.

Installation

go get github.com/massengine-dev/massengine-go@v1.1.4

Quickstart

package main

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

	massengine "github.com/massengine-dev/massengine-go"
)

func main() {
	ctx := context.Background()
	cli := massengine.New(massengine.Options{
		BaseURL: "https://massengine.com",
		APIKey:  "mk_your_tenant_api_key",
	})

	// 1. Ingest dense vectors + structured metadata
	_, _ = cli.Ingest(ctx, "acme-prod", []massengine.Doc{
		{
			ID:       "docs/2026/policy-1",
			Vector:   []float32{0.12, -0.44, 0.88, 0.05},
			Category: 1,
			Metadata: json.RawMessage(`{"department":"security","clearance":3,"tags":["soc2","policy"]}`),
		},
	})

	// 2. Dense vector search with rich metadata pre-filters
	res, _ := cli.Search(ctx, massengine.SearchRequest{
		Tenant: "acme-prod",
		Vector: []float32{0.12, -0.44, 0.88, 0.05},
		K:      10,
		MetadataFilter: map[string]any{
			"department": map[string]any{"$in": []string{"security", "legal"}},
			"clearance":  map[string]any{"$gte": 2},
			"tags":       map[string]any{"$contains": "soc2"},
		},
	})
	fmt.Printf("Hits: %+v\n", res.Hits)
}

Multi-Database Scoping

Create isolated databases within a tenant and scope reads/writes to a specific database (pass tenant = "" when authenticating with a tenant-scoped mk_... key):

_, _ = cli.CreateDatabase(ctx, "", massengine.DatabaseConfig{
	Database: "analytics",
	DataType: "int8",
})

_, _ = cli.IngestDatabase(ctx, "", "analytics", []massengine.Doc{
	{ID: "event-1", Vector: []float32{0.1, 0.2, 0.3, 0.4}},
})

res, _ := cli.Search(ctx, massengine.SearchRequest{
	Database: "analytics",
	Vector:   []float32{0.1, 0.2, 0.3, 0.4},
	K:        5,
})

License

Apache License 2.0

Documentation

Overview

Package massengine provides the official Go client SDK for the MassEngine filtered vector search REST API.

Index

Constants

View Source 
const (
	// Version is the semantic version of this SDK release.
	Version = "1.1.4"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
}

APIError is returned when the server responds with a non-2xx HTTP status.

func (*APIError) Error 

func (e *APIError) Error() string

type BatchSearchResponse 

type BatchSearchResponse struct {
	Results []SearchResponse `json:"results"`
}

BatchSearchResponse is returned by BatchSearch.

type Client 

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

Client is the official Go SDK client for the MassEngine HTTP REST API.

func New 

func New(opts Options) *Client

New constructs a MassEngine client. If opts contains an invalid BaseURL or APIKey, all subsequent requests on the returned Client fail immediately with that validation error without making network calls.

func NewClient 

func NewClient(opts Options) (*Client, error)

NewClient constructs and validates a MassEngine client, returning an error if BaseURL or APIKey is invalid.

func (*Client) BatchGetDocs 

func (c *Client) BatchGetDocs(ctx context.Context, tenant string, ids []string, database ...string) ([]DocResponse, error)

BatchGetDocs fetches multiple documents by ID in a single request, optionally scoped to database.

func (*Client) BatchSearch 

func (c *Client) BatchSearch(ctx context.Context, queries []SearchRequest, database ...string) (*BatchSearchResponse, error)

BatchSearch executes multiple dense vector queries in a single round-trip, with an optional batch-level default database name.

func (*Client) Compact 

func (c *Client) Compact(ctx context.Context) error

Compact optimizes storage segments.

func (*Client) CreateDatabase added in v1.1.4 

func (c *Client) CreateDatabase(ctx context.Context, tenant string, cfg DatabaseConfig) (*DatabaseInfo, error)

CreateDatabase creates or updates a named database under tenant (or under the bound mk_... key's tenant when tenant is empty).

func (*Client) CreateTenantKey 

func (c *Client) CreateTenantKey(ctx context.Context, tenant, key string) (string, error)

CreateTenantKey registers (or generates if key is empty) a tenant-scoped bearer API key. Requires the admin API key.

func (*Client) DeleteDatabase added in v1.1.4 

func (c *Client) DeleteDatabase(ctx context.Context, tenant, database string) (int, error)

DeleteDatabase purges all documents and routing state for a named database.

func (*Client) DeleteDoc 

func (c *Client) DeleteDoc(ctx context.Context, tenant, id string, database ...string) error

DeleteDoc deletes a document by ID, optionally scoped to database.

func (*Client) DeleteTenant 

func (c *Client) DeleteTenant(ctx context.Context, tenant string) (int, error)

DeleteTenant deletes all documents and state for tenant.

func (*Client) ExportTenant 

func (c *Client) ExportTenant(ctx context.Context, tenant string, database ...string) ([]Doc, error)

ExportTenant streams all live documents belonging to tenant (or the bound mk_... key's tenant when tenant is empty) via NDJSON, optionally filtered to a single database.

func (*Client) Flush 

func (c *Client) Flush(ctx context.Context) error

Flush persists buffered writes to durable storage.

func (*Client) GetDatabase added in v1.1.4 

func (c *Client) GetDatabase(ctx context.Context, tenant, database string) (*DatabaseInfo, error)

GetDatabase fetches metadata and volume statistics for a single named database.

func (*Client) GetDoc 

func (c *Client) GetDoc(ctx context.Context, tenant, id string, database ...string) (*DocResponse, error)

GetDoc fetches a document's metadata by ID, optionally scoped to database.

func (*Client) GetTenant 

func (c *Client) GetTenant(ctx context.Context, tenant string, database ...string) (*TenantSummary, error)

GetTenant returns volume metadata for a single tenant (or database when optional database is specified).

func (*Client) GetTenantQuota 

func (c *Client) GetTenantQuota(ctx context.Context, tenant string) (*TenantQuota, error)

GetTenantQuota retrieves the active quota configuration for tenant.

func (*Client) GetTenantUsage 

func (c *Client) GetTenantUsage(ctx context.Context, tenant string) (*TenantUsage, error)

GetTenantUsage returns cumulative billable read/write counters, byte footprint, and search latency percentiles for tenant.

func (*Client) GoString 

func (c *Client) GoString() string

GoString returns a redacted Go-syntax representation that never exposes credentials.

func (*Client) Health added in v1.1.4 

func (c *Client) Health(ctx context.Context) (bool, error)

Health checks gateway liveness via GET /v1/health.

func (*Client) ImportTenant 

func (c *Client) ImportTenant(ctx context.Context, tenant string, docs []Doc, database ...string) (int, error)

ImportTenant streams a slice of documents as NDJSON into tenant (or the bound mk_... key's tenant when tenant is empty), optionally scoped to database.

func (*Client) Ingest 

func (c *Client) Ingest(ctx context.Context, tenant string, docs []Doc, database ...string) (*IngestResponse, error)

Ingest writes or upserts a batch of documents for tenant (or the tenant bound to a tenant-scoped mk_... API key when tenant is empty), with an optional target database name.

func (*Client) IngestDatabase added in v1.1.4 

func (c *Client) IngestDatabase(ctx context.Context, tenant, database string, docs []Doc) (*IngestResponse, error)

IngestDatabase writes or upserts a batch of documents into the specified database for tenant (or into the bound mk_... key's tenant when tenant is empty).

func (*Client) ListDatabases added in v1.1.4 

func (c *Client) ListDatabases(ctx context.Context, tenant string) ([]DatabaseInfo, error)

ListDatabases lists all databases configured under tenant (or under the bound mk_... key's tenant when tenant is empty).

func (*Client) ListTenants 

func (c *Client) ListTenants(ctx context.Context) ([]TenantSummary, error)

ListTenants lists all known tenants.

func (*Client) ListUsage 

func (c *Client) ListUsage(ctx context.Context) (*UsageReport, error)

ListUsage returns the cluster-wide usage report across all tenants. Requires the admin API key.

func (*Client) PatchDoc 

func (c *Client) PatchDoc(ctx context.Context, tenant, id string, req PatchRequest, database ...string) (*DocResponse, error)

PatchDoc updates an existing document's metadata, date, or category in place without re-supplying its vector.

func (*Client) Ready 

func (c *Client) Ready(ctx context.Context) (*ReadyStatus, error)

Ready checks service readiness. Both HTTP 200 and HTTP 503 JSON readiness payloads return a populated ReadyStatus without an error.

func (*Client) RevokeTenantKey 

func (c *Client) RevokeTenantKey(ctx context.Context, tenant, key string) error

RevokeTenantKey revokes a tenant-scoped bearer API key. Requires the admin API key.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, req SearchRequest) (*SearchResponse, error)

Search executes a single dense vector query with optional metadata, date, and category filters.

func (*Client) SetTenantQuota 

func (c *Client) SetTenantQuota(ctx context.Context, tenant string, quota TenantQuota) (*TenantQuota, error)

SetTenantQuota configures a tenant's plan tier, MaxDocs/MaxBytes caps, MaxQPS limit, and suspension state. Requires the admin API key.

func (*Client) String 

func (c *Client) String() string

String returns a redacted representation that never exposes credentials.

type DatabaseConfig added in v1.1.4 

type DatabaseConfig struct {
	Database  string `json:"database"`
	NumShards int    `json:"num_shards,omitempty"`
	RF        int    `json:"rf,omitempty"`
	Mode      string `json:"mode,omitempty"`
	DataType  string `json:"data_type,omitempty"`
}

DatabaseConfig specifies configuration options when creating or updating a named database within a tenant.

type DatabaseInfo added in v1.1.4 

type DatabaseInfo struct {
	Tenant         string `json:"tenant"`
	Database       string `json:"database,omitempty"`
	Partition      string `json:"partition,omitempty"`
	Tag            uint32 `json:"tag,omitempty"`
	Mode           string `json:"mode,omitempty"`
	PinnedShard    int    `json:"pinned_shard"`
	NumShards      int    `json:"num_shards,omitempty"`
	RF             int    `json:"rf,omitempty"`
	DataType       string `json:"data_type,omitempty"`
	ExplicitShards bool   `json:"explicit_shards,omitempty"`
	DocCount       uint64 `json:"doc_count"`
	ByteCount      uint64 `json:"byte_count,omitempty"`
}

DatabaseInfo describes a database's routing configuration and storage volume.

type Doc 

type Doc struct {
	ID       string          `json:"id"`
	Database string          `json:"database,omitempty"`
	Vector   []float32       `json:"vector"`
	Date     uint16          `json:"date,omitempty"`
	Category uint16          `json:"category,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

Doc represents a document submitted via Ingest or ImportTenant.

type DocResponse 

type DocResponse struct {
	ID       string          `json:"id"`
	Tenant   string          `json:"tenant,omitempty"`
	Database string          `json:"database,omitempty"`
	Date     uint16          `json:"date,omitempty"`
	Category uint16          `json:"category,omitempty"`
	Found    bool            `json:"found"`
	Degraded bool            `json:"degraded,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

DocResponse is returned by GetDoc, PatchDoc, and BatchGetDocs.

type Hit 

type Hit struct {
	ID       string          `json:"id"`
	DocID    uint64          `json:"doc_id"`
	Score    float32         `json:"score"`
	Shard    int             `json:"shard"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

Hit is a single search result returned by Search or BatchSearch.

type IngestResponse 

type IngestResponse struct {
	Ingested int    `json:"ingested"`
	Degraded bool   `json:"degraded"`
	Database string `json:"database,omitempty"`
}

IngestResponse is returned by Ingest and IngestDatabase.

type LatencyBucket added in v1.1.4 

type LatencyBucket struct {
	LeMs  string `json:"le_ms"`
	Count uint64 `json:"count"`
}

LatencyBucket represents one cumulative histogram bucket in LatencyStats.

type LatencyStats added in v1.1.4 

type LatencyStats struct {
	Count   uint64          `json:"count"`
	AvgMs   float64         `json:"avg_ms"`
	P50Ms   float64         `json:"p50_ms"`
	P95Ms   float64         `json:"p95_ms"`
	P99Ms   float64         `json:"p99_ms"`
	Buckets []LatencyBucket `json:"buckets,omitempty"`
}

LatencyStats summarizes search latency percentiles and histogram buckets.

type Options 

type Options struct {
	BaseURL          string
	APIKey           string
	HTTPClient       *http.Client
	Timeout          time.Duration
	MaxResponseBytes int64
}

Options configures a MassEngine HTTP Client.

type PatchRequest 

type PatchRequest struct {
	Database    string          `json:"database,omitempty"`
	Date        *uint16         `json:"date,omitempty"`
	Category    *uint16         `json:"category,omitempty"`
	Metadata    json.RawMessage `json:"metadata,omitempty"`
	ReplaceMeta bool            `json:"replace_metadata,omitempty"`
}

PatchRequest specifies an in-place metadata, date, or category update without re-embedding the document vector.

type ReadyStatus 

type ReadyStatus struct {
	Ready             bool  `json:"ready"`
	UnavailableShards []int `json:"unavailable_shards,omitempty"`
}

ReadyStatus is returned by Ready.

type SearchRequest 

type SearchRequest struct {
	Tenant         string         `json:"tenant,omitempty"`
	Database       string         `json:"database,omitempty"`
	Vector         []float32      `json:"vector"`
	MetadataFilter map[string]any `json:"metadata_filter,omitempty"`
	K              int            `json:"k"`
	Offset         int            `json:"offset,omitempty"`
	MinScore       *float32       `json:"min_score,omitempty"`
	RerankPool     int            `json:"rerank_pool,omitempty"`
	NProbe         int            `json:"nprobe,omitempty"`
	MinDate        *uint16        `json:"min_date,omitempty"`
	MaxDate        *uint16        `json:"max_date,omitempty"`
	Category       *uint16        `json:"category,omitempty"`
	Categories     []uint16       `json:"categories,omitempty"`
}

SearchRequest specifies a dense vector query with optional database scope, metadata/date/category pre-filters, similarity threshold, and pagination offset.

type SearchResponse 

type SearchResponse struct {
	Hits   []Hit   `json:"hits"`
	TookMs float64 `json:"took_ms,omitempty"`
}

SearchResponse is returned by Search.

type TenantQuota 

type TenantQuota struct {
	Plan      string  `json:"plan,omitempty"`
	MaxDocs   uint64  `json:"max_docs,omitempty"`
	MaxBytes  uint64  `json:"max_bytes,omitempty"`
	MaxQPS    float64 `json:"max_qps,omitempty"`
	Burst     int     `json:"burst,omitempty"`
	Suspended bool    `json:"suspended,omitempty"`
}

TenantQuota defines a tenant's plan tier, document and byte capacity limits, QPS rate limit, and billing suspension state.

type TenantSummary 

type TenantSummary struct {
	Tenant      string `json:"tenant"`
	Database    string `json:"database,omitempty"`
	Partition   string `json:"partition,omitempty"`
	Mode        string `json:"mode,omitempty"`
	PinnedShard int    `json:"pinned_shard,omitempty"`
	NumShards   int    `json:"num_shards,omitempty"`
	RF          int    `json:"rf,omitempty"`
	DataType    string `json:"data_type,omitempty"`
	DocCount    uint64 `json:"doc_count"`
	ByteCount   uint64 `json:"byte_count,omitempty"`
}

TenantSummary describes a tenant's document and storage volume.

type TenantUsage 

type TenantUsage struct {
	Tenant         string       `json:"tenant"`
	Plan           string       `json:"plan,omitempty"`
	Suspended      bool         `json:"suspended,omitempty"`
	PartitionCount int          `json:"partition_count"`
	LiveDocs       uint64       `json:"live_docs"`
	LiveBytes      uint64       `json:"live_bytes"`
	MaxDocs        uint64       `json:"max_docs,omitempty"`
	MaxBytes       uint64       `json:"max_bytes,omitempty"`
	MaxQPS         float64      `json:"max_qps,omitempty"`
	ReadRequests   uint64       `json:"read_requests"`
	ReadUnits      uint64       `json:"read_units"`
	WriteRequests  uint64       `json:"write_requests"`
	WriteUnits     uint64       `json:"write_units"`
	RateLimited    uint64       `json:"rate_limited"`
	SearchLatency  LatencyStats `json:"search_latency"`
	UpdatedAt      string       `json:"updated_at,omitempty"`
}

TenantUsage reports cumulative billable read/write counters, logical byte footprint, and search latency percentiles for a single tenant.

type UsageReport 

type UsageReport struct {
	Tenants         []TenantUsage `json:"tenants"`
	TotalLiveDocs   uint64        `json:"total_live_docs"`
	TotalLiveBytes  uint64        `json:"total_live_bytes"`
	TotalReadUnits  uint64        `json:"total_read_units"`
	TotalWriteUnits uint64        `json:"total_write_units"`
}

UsageReport aggregates per-tenant usage across the cluster.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.