massengine

package module
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 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 and hybrid vector search database.

Installation

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

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://api.massengine.com",
		APIKey:  "mk_your_tenant_api_key",
	})

	_, _ = cli.Ingest(ctx, "acme-prod", []massengine.Doc{
		{
			ID:       "doc-1",
			Vector:   []float32{0.12, -0.44, 0.88, 0.05},
			Category: 1,
			Metadata: json.RawMessage(`{"department":"security","clearance":3}`),
		},
	})

	res, _ := cli.Search(ctx, massengine.SearchRequest{
		Tenant:    "acme-prod",
		Vector:    []float32{0.12, -0.44, 0.88, 0.05},
		QueryText: "security compliance",
		K:         10,
		MetadataFilter: map[string]any{
			"department": map[string]any{"$in": []string{"security", "legal"}},
			"clearance":  map[string]any{"$gte": 2},
		},
	})
	fmt.Printf("Hits: %+v\n", res.Hits)
}

License

Apache License 2.0

Documentation

Overview

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

Index

Constants

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

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) ([]DocResponse, error)

BatchGetDocs fetches multiple documents by ID in a single request.

func (*Client) BatchSearch 

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

BatchSearch executes multiple queries in a single round-trip.

func (*Client) Compact 

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

Compact optimizes storage segments.

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) DeleteDoc 

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

DeleteDoc deletes a document by ID.

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) ([]Doc, error)

ExportTenant streams all live documents belonging to tenant via NDJSON.

func (*Client) Flush 

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

Flush persists buffered writes to durable storage.

func (*Client) GetDoc 

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

GetDoc fetches a document's metadata by ID.

func (*Client) GetTenant 

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

GetTenant returns volume metadata for a single tenant.

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 and capacity utilization for tenant.

func (*Client) GoString 

func (c *Client) GoString() string

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

func (*Client) ImportTenant 

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

ImportTenant streams a slice of documents as NDJSON into tenant.

func (*Client) Ingest 

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

Ingest writes or upserts a batch of documents for tenant.

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) (*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.

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 vector, lexical, or hybrid query.

func (*Client) SetTenantQuota 

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

SetTenantQuota configures a tenant's plan tier, MaxDocs cap, 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 Doc 

type Doc struct {
	ID       string          `json:"id"`
	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"`
	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"`
}

IngestResponse is returned by Ingest.

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 {
	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"`
	Vector         []float32      `json:"vector,omitempty"`
	QueryText      string         `json:"query_text,omitempty"`
	HybridAlpha    float32        `json:"hybrid_alpha,omitempty"`
	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 vector, lexical, or hybrid query with optional 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"`
	MaxQPS    float64 `json:"max_qps,omitempty"`
	Burst     int     `json:"burst,omitempty"`
	Suspended bool    `json:"suspended,omitempty"`
}

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

type TenantSummary 

type TenantSummary struct {
	Tenant    string `json:"tenant"`
	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"`
	LiveDocs      uint64  `json:"live_docs"`
	MaxDocs       uint64  `json:"max_docs,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"`
	UpdatedAt     string  `json:"updated_at,omitempty"`
}

TenantUsage reports cumulative billable read/write counters and capacity utilization for a single tenant.

type UsageReport 

type UsageReport struct {
	Tenants         []TenantUsage `json:"tenants"`
	TotalLiveDocs   uint64        `json:"total_live_docs"`
	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.