SDKs#

Antfly provides type-safe client libraries for Go, TypeScript, Python, and Rust. The Go, TypeScript, and Python SDKs are hand-written clients over code generated from the OpenAPI specification; the Rust SDK is generated from it end to end.

Language	Package	Registry	Source
Go	`github.com/antflydb/antfly/go/pkg/sdk`	pkg.go.dev	GitHub
TypeScript	`@antfly/sdk`	npm	GitHub
Python	`antfly-sdk`	PyPI	GitHub
Rust	`antfly-sdk`	Not yet published; use a git dependency	GitHub

Embedded Lite Binding#

Antfly Lite embeds Antfly directly in an application process with a live .aflite database file. The first Lite binding above Zig and C is Go:

go get github.com/antflydb/antfly/go/pkg/antflylite

The Lite binding is separate from the network SDK. Use github.com/antflydb/antfly/go/pkg/sdk for a running Antfly service and github.com/antflydb/antfly/go/pkg/antflylite for embedded local databases.

See the Antfly Lite guide for CLI and Go embedded examples, plus backup, restore, and promotion between Lite and a running instance.

Installation#

go get github.com/antflydb/antfly/go/pkg/sdk

npm install @antfly/sdk

pip install antfly-sdk

# Cargo.toml
[dependencies]
antfly-sdk = { git = "https://github.com/antflydb/antfly" }

Authentication#

All three authentication methods are supported across SDKs: basic auth, API key, and token.

Basic Auth#

import (
	antfly "github.com/antflydb/antfly/go/pkg/sdk"
	"github.com/antflydb/antfly/go/pkg/sdk/oapi"
)

client, err := antfly.NewAntflyClientWithOptions(
	"http://127.0.0.1:8080",
	oapi.WithRequestEditorFn(antfly.WithBasicAuth("admin", "password")),
)

import { AntflyClient } from '@antfly/sdk';

const client = new AntflyClient({
  baseUrl: 'http://127.0.0.1:8080',
  auth: {
    username: 'admin',
    password: 'password',
  },
});

from antfly import AntflyClient

client = AntflyClient(
    base_url='http://127.0.0.1:8080',
    username='admin',
    password='password',
)

// Cargo.toml also needs: base64 = "0.22"
use antfly_sdk::new_client;
use base64::Engine as _;
use reqwest::header::{AUTHORIZATION, HeaderMap, HeaderValue};

let encoded = base64::engine::general_purpose::STANDARD.encode("admin:password");
let mut headers = HeaderMap::new();
headers.insert(
    AUTHORIZATION,
    HeaderValue::from_str(&format!("Basic {encoded}"))?,
);

let client = new_client(
    "http://127.0.0.1:8080",
    reqwest::Client::builder().default_headers(headers).build()?,
);

API Key#

client, err := antfly.NewAntflyClientWithOptions(
	"http://127.0.0.1:8080",
	oapi.WithRequestEditorFn(antfly.WithApiKey("key-id", "key-secret")),
)

const client = new AntflyClient({
  baseUrl: 'http://127.0.0.1:8080',
  auth: {
    type: 'apiKey',
    keyId: 'key-id',
    keySecret: 'key-secret',
  },
});

client = AntflyClient(
    base_url='http://127.0.0.1:8080',
    api_key=('key-id', 'key-secret'),
)

// Cargo.toml also needs: base64 = "0.22"
use antfly_sdk::new_client;
use base64::Engine as _;
use reqwest::header::{AUTHORIZATION, HeaderMap, HeaderValue};

let encoded = base64::engine::general_purpose::STANDARD.encode("key-id:key-secret");
let mut headers = HeaderMap::new();
headers.insert(
    AUTHORIZATION,
    HeaderValue::from_str(&format!("ApiKey {encoded}"))?,
);

let client = new_client(
    "http://127.0.0.1:8080",
    reqwest::Client::builder().default_headers(headers).build()?,
);

Token#

client, err := antfly.NewAntflyClientWithOptions(
	"http://127.0.0.1:8080",
	oapi.WithRequestEditorFn(antfly.WithToken("your-token")),
)

const client = new AntflyClient({
  baseUrl: 'http://127.0.0.1:8080',
  auth: {
    type: 'token',
    token: 'your-token',
  },
});

client = AntflyClient(
    base_url='http://127.0.0.1:8080',
    token='your-token',
)

use antfly_sdk::new_client_with_token;

let client = new_client_with_token("http://127.0.0.1:8080", "your-token")?;

Quick Start#

Insert Documents#

import (
	"context"
	"log"

	antfly "github.com/antflydb/antfly/go/pkg/sdk"
	"github.com/antflydb/antfly/go/pkg/sdk/oapi"
)

ctx := context.Background()
client, err := antfly.NewAntflyClientWithOptions(
	"http://127.0.0.1:8080",
	oapi.WithRequestEditorFn(antfly.WithBasicAuth("admin", "password")),
)
if err != nil {
	log.Fatal(err)
}

// Batch insert documents
result, err := client.Batch(ctx, "products", antfly.BatchRequest{
	Inserts: map[string]any{
		"prod:001": map[string]any{
			"name":  "Laptop",
			"price": 1299.99,
		},
		"prod:002": map[string]any{
			"name":  "Mouse",
			"price": 29.99,
		},
	},
})

import { AntflyClient } from '@antfly/sdk';

const client = new AntflyClient({
  baseUrl: 'http://127.0.0.1:8080',
  auth: { username: 'admin', password: 'password' },
});

// Batch insert documents
await client.tables.batch('products', {
  inserts: {
    'prod:001': { name: 'Laptop', price: 1299.99 },
    'prod:002': { name: 'Mouse', price: 29.99 },
  },
});

from antfly import AntflyClient

client = AntflyClient(
    base_url='http://127.0.0.1:8080',
    username='admin',
    password='password',
)

# Batch insert documents
client.batch(
    table='products',
    inserts={
        'prod:001': {'name': 'Laptop', 'price': 1299.99},
        'prod:002': {'name': 'Mouse', 'price': 29.99},
    },
)

use antfly_sdk::new_client;
use antfly_sdk::types::BatchRequest;
use serde_json::json;
use std::collections::HashMap;

let client = new_client("http://127.0.0.1:8080", reqwest::Client::new());

// Batch insert documents. Each value is a JSON object.
let mut inserts = HashMap::new();
inserts.insert(
    "prod:001".to_string(),
    json!({"name": "Laptop", "price": 1299.99}).as_object().unwrap().clone(),
);
inserts.insert(
    "prod:002".to_string(),
    json!({"name": "Mouse", "price": 29.99}).as_object().unwrap().clone(),
);

client
    .batch_write(
        "products",
        &BatchRequest {
            inserts,
            ..Default::default()
        },
    )
    .await?;

Query#

import "github.com/antflydb/antfly/go/pkg/sdk/query"

fullText := query.NewQueryString("laptop")
results, err := client.Query(ctx, antfly.QueryRequest{
	Table:          "products",
	FullTextSearch: &fullText,
	Limit:          10,
})
if err != nil {
	log.Fatal(err)
}

for _, hit := range results.Responses[0].Hits.Hits {
	fmt.Printf("%s: %v\n", hit.ID, hit.Source)
}

const results = await client.query({
  table: 'products',
  full_text_search: { query: 'laptop' },
  limit: 10,
});

for (const hit of results?.hits?.hits ?? []) {
  console.log(hit._id, hit._source);
}

results = client.query(
    table='products',
    full_text_search={'query': 'laptop'},
    limit=10,
)

for hit in results.responses[0].hits.hits:
    print(hit.field_id, hit.field_source)

Rust has no query sample. Its client is generated straight from the OpenAPI spec by progenitor, and the generated QueryRequest carries only table, fields, hierarchy, limit, and timeout_ms, so it cannot express full_text_search or semantic_search. Send search requests over HTTP directly until the generated request type covers them.

React Components#

For search UIs, @antfly/components is a React component library with search boxes, facets, result lists, and answer boxes. Add Search and AI Answers to Your Site builds a page with it; the React Antfly reference covers every component.

npm install @antfly/components @antfly/sdk