ArcherDB API Reference

import { createGeoClient, createGeoEvent, id } from 'archerdb-node'

const client = await createGeoClient({
  cluster_id: 0n,
  addresses: ['127.0.0.1:3000'],
})

// Create a batch
const batch = client.createBatch()

// Add events
batch.add(createGeoEvent({
  entity_id: id(),
  latitude: 37.7749,
  longitude: -122.4194,
  group_id: 1n,
}))

batch.add(createGeoEvent({
  entity_id: id(),
  latitude: 37.7849,
  longitude: -122.4094,
  group_id: 1n,
}))

// Commit (default: insert mode)
const results = await batch.commit()

// Check per-event results
for (const result of results) {
  if (result.error) {
    console.error(`Event ${result.index} failed: ${result.error}`)
  }
}

// Or use upsert mode (idempotent)
const upsertBatch = client.createBatch({ mode: 'upsert' })
// ... add events ...
await upsertBatch.commit()

import archerdb

client = archerdb.GeoClientSync(archerdb.GeoClientConfig(
    cluster_id=0,
    addresses=['127.0.0.1:3000']
))

# Create a batch
batch = client.create_batch()

# Add events
batch.add(archerdb.create_geo_event(
    entity_id=archerdb.id(),
    latitude=37.7749,
    longitude=-122.4194,
    group_id=1,
))

batch.add(archerdb.create_geo_event(
    entity_id=archerdb.id(),
    latitude=37.7849,
    longitude=-122.4094,
    group_id=1,
))

# Commit
results = batch.commit()

# Check per-event results
for result in results:
    if result.error:
        print(f"Event {result.index} failed: {result.error}")

import (
    archerdb "github.com/ArcherDB-io/archerdb/src/clients/go"
    "github.com/ArcherDB-io/archerdb/src/clients/go/pkg/types"
)

client, err := archerdb.NewClient(types.ToUint128(0), []string{"127.0.0.1:3000"})
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Create events
events := []types.GeoEvent{
    {
        EntityID: types.ID(),
        LatNano:  37774900000,
        LonNano:  -122419400000,
        GroupID:  1,
    },
    {
        EntityID: types.ID(),
        LatNano:  37784900000,
        LonNano:  -122409400000,
        GroupID:  1,
    },
}

// Insert events
results, err := client.CreateEvents(events)
if err != nil {
    log.Fatal(err)
}

// Check per-event results
for _, result := range results {
    if result.Result != 0 {
        log.Printf("Event %d failed: %v", result.Index, result.Result)
    }
}

import com.archerdb.geo.*;
import java.math.BigInteger;
import java.util.List;

GeoClientConfig config = new GeoClientConfig.Builder()
    .clusterId(BigInteger.ZERO)
    .addresses(List.of("127.0.0.1:3000"))
    .build();

try (GeoClient client = new GeoClient(config)) {
    // Create events
    List<GeoEvent> events = List.of(
        GeoEvent.builder()
            .entityId(GeoClient.generateId())
            .latNano(37774900000L)
            .lonNano(-122419400000L)
            .groupId(1L)
            .build(),
        GeoEvent.builder()
            .entityId(GeoClient.generateId())
            .latNano(37784900000L)
            .lonNano(-122409400000L)
            .groupId(1L)
            .build()
    );

    // Insert events
    List<EventResult> results = client.createEvents(events);

    // Check per-event results
    for (EventResult result : results) {
        if (result.getResult() != 0) {
            System.err.println("Event " + result.getIndex() + " failed: " + result.getResult());
        }
    }
}

#include <archerdb.h>
#include <stdio.h>

arch_client_t* client = arch_client_new(0, "127.0.0.1:3000", NULL);

// Create events
geo_event_t events[2] = {
    {
        .entity_id = arch_id(),
        .lat_nano = 37774900000,
        .lon_nano = -122419400000,
        .group_id = 1,
    },
    {
        .entity_id = arch_id(),
        .lat_nano = 37784900000,
        .lon_nano = -122409400000,
        .group_id = 1,
    },
};

// Insert events (synchronous callback)
void on_result(void* ctx, const event_result_t* results, size_t count) {
    for (size_t i = 0; i < count; i++) {
        if (results[i].result != 0) {
            printf("Event %u failed: %u\n", results[i].index, results[i].result);
        }
    }
}

arch_create_events(client, events, 2, on_result, NULL);

arch_client_destroy(client);

// Basic query
const results = await client.queryRadius({
  center_lat: 37.7749,
  center_lon: -122.4194,
  radius_m: 1000,
  limit: 100,
})

console.log(`Found ${results.events.length} entities`)

// With group filter
const fleetResults = await client.queryRadius({
  center_lat: 37.7749,
  center_lon: -122.4194,
  radius_m: 5000,
  group_id: 1n,  // Only fleet 1
  limit: 100,
})

// Pagination
let allEvents = []
let cursor = undefined

do {
  const page = await client.queryRadius({
    center_lat: 37.7749,
    center_lon: -122.4194,
    radius_m: 10000,
    limit: 1000,
    cursor,
  })
  allEvents.push(...page.events)
  cursor = page.has_more ? page.cursor : undefined
} while (cursor)

# Basic query
results = client.query_radius(
    center_lat=37.7749,
    center_lon=-122.4194,
    radius_m=1000,
    limit=100,
)

print(f"Found {len(results.events)} entities")

# With group filter
fleet_results = client.query_radius(
    center_lat=37.7749,
    center_lon=-122.4194,
    radius_m=5000,
    group_id=1,  # Only fleet 1
    limit=100,
)

# Pagination
all_events = []
cursor = None

while True:
    page = client.query_radius(
        center_lat=37.7749,
        center_lon=-122.4194,
        radius_m=10000,
        limit=1000,
        cursor=cursor,
    )
    all_events.extend(page.events)
    if not page.has_more:
        break
    cursor = page.cursor

// Basic query
filter := types.RadiusFilter{
    CenterLatNano: 37774900000,
    CenterLonNano: -122419400000,
    RadiusM:       1000,
    Limit:         100,
}

results, err := client.QueryRadius(filter)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d entities\n", len(results.Events))

// Pagination
var allEvents []types.GeoEvent
var cursor []byte

for {
    filter := types.RadiusFilter{
        CenterLatNano: 37774900000,
        CenterLonNano: -122419400000,
        RadiusM:       10000,
        Limit:         1000,
        Cursor:        cursor,
    }

    page, err := client.QueryRadius(filter)
    if err != nil {
        log.Fatal(err)
    }

    allEvents = append(allEvents, page.Events...)
    if !page.HasMore {
        break
    }
    cursor = page.Cursor
}

// Basic query
QueryRadiusFilter filter = new QueryRadiusFilter.Builder()
    .centerLatNano(37774900000L)
    .centerLonNano(-122419400000L)
    .radiusM(1000)
    .limit(100)
    .build();

QueryResult results = client.queryRadius(filter);
System.out.println("Found " + results.getEvents().size() + " entities");

// Pagination
List<GeoEvent> allEvents = new ArrayList<>();
byte[] cursor = null;

do {
    QueryRadiusFilter pageFilter = new QueryRadiusFilter.Builder()
        .centerLatNano(37774900000L)
        .centerLonNano(-122419400000L)
        .radiusM(10000)
        .limit(1000)
        .cursor(cursor)
        .build();

    QueryResult page = client.queryRadius(pageFilter);
    allEvents.addAll(page.getEvents());
    cursor = page.hasMore() ? page.getCursor() : null;
} while (cursor != null);

// Basic query
radius_filter_t filter = {
    .center_lat_nano = 37774900000,
    .center_lon_nano = -122419400000,
    .radius_m = 1000,
    .limit = 100,
};

void on_result(void* ctx, const geo_event_t* events, size_t count, bool has_more, const uint8_t* cursor, size_t cursor_len) {
    printf("Found %zu entities\n", count);

    // Handle pagination if needed
    if (has_more) {
        // Store cursor for next query
    }
}

arch_query_radius(client, &filter, on_result, NULL);

// Simple polygon (downtown San Francisco)
const results = await client.queryPolygon({
  vertices: [
    { lat: 37.79, lon: -122.42 },  // NW
    { lat: 37.79, lon: -122.39 },  // NE
    { lat: 37.76, lon: -122.39 },  // SE
    { lat: 37.76, lon: -122.42 },  // SW
  ],
  limit: 1000,
})

// Polygon with hole (exclude a park)
const resultsWithHole = await client.queryPolygon({
  vertices: [
    { lat: 37.79, lon: -122.42 },
    { lat: 37.79, lon: -122.39 },
    { lat: 37.76, lon: -122.39 },
    { lat: 37.76, lon: -122.42 },
  ],
  holes: [
    // Park to exclude (clockwise winding)
    [
      { lat: 37.78, lon: -122.41 },
      { lat: 37.775, lon: -122.41 },
      { lat: 37.775, lon: -122.40 },
      { lat: 37.78, lon: -122.40 },
    ],
  ],
  limit: 1000,
})

# Simple polygon
results = client.query_polygon(
    vertices=[
        (37.79, -122.42),  # NW
        (37.79, -122.39),  # NE
        (37.76, -122.39),  # SE
        (37.76, -122.42),  # SW
    ],
    limit=1000,
)

# Polygon with hole
results_with_hole = client.query_polygon(
    vertices=[
        (37.79, -122.42),
        (37.79, -122.39),
        (37.76, -122.39),
        (37.76, -122.42),
    ],
    holes=[
        # Park to exclude (clockwise winding)
        [
            (37.78, -122.41),
            (37.775, -122.41),
            (37.775, -122.40),
            (37.78, -122.40),
        ],
    ],
    limit=1000,
)

// Simple polygon
vertices := [][]float64{
    {37.79, -122.42},
    {37.79, -122.39},
    {37.76, -122.39},
    {37.76, -122.42},
}

filter, err := types.NewPolygonQuery(vertices, 1000)
if err != nil {
    log.Fatal(err)
}

results, err := client.QueryPolygon(filter)

// Polygon with hole
parkHole := [][]float64{
    {37.78, -122.41},
    {37.775, -122.41},
    {37.775, -122.40},
    {37.78, -122.40},
}

filterWithHole, err := types.NewPolygonQuery(vertices, 1000, parkHole)

// Simple polygon
QueryPolygonFilter filter = new QueryPolygonFilter.Builder()
    .addVertex(37.79, -122.42)
    .addVertex(37.79, -122.39)
    .addVertex(37.76, -122.39)
    .addVertex(37.76, -122.42)
    .setLimit(1000)
    .build();

QueryResult results = client.queryPolygon(filter);

// Polygon with hole
QueryPolygonFilter filterWithHole = new QueryPolygonFilter.Builder()
    .addVertex(37.79, -122.42)
    .addVertex(37.79, -122.39)
    .addVertex(37.76, -122.39)
    .addVertex(37.76, -122.42)
    .startHole()
    .addHoleVertex(37.78, -122.41)
    .addHoleVertex(37.775, -122.41)
    .addHoleVertex(37.775, -122.40)
    .addHoleVertex(37.78, -122.40)
    .finishHole()
    .setLimit(1000)
    .build();

// Simple polygon
coordinate_t vertices[] = {
    {.lat = 37.79, .lon = -122.42},
    {.lat = 37.79, .lon = -122.39},
    {.lat = 37.76, .lon = -122.39},
    {.lat = 37.76, .lon = -122.42},
};

polygon_filter_t filter = {
    .vertices = vertices,
    .vertex_count = 4,
    .limit = 1000,
};

arch_query_polygon(client, &filter, on_result, NULL);

const event = await client.getLatest(entityId)

if (event) {
  console.log(`Last seen at: ${event.lat_nano / 1e9}, ${event.lon_nano / 1e9}`)
} else {
  console.log('Entity not found')
}

event = client.get_latest(entity_id)

if event:
    print(f"Last seen at: {event.lat_nano / 1e9}, {event.lon_nano / 1e9}")
else:
    print("Entity not found")

event, found, err := client.GetLatest(entityID)
if err != nil {
    log.Fatal(err)
}

if found {
    fmt.Printf("Last seen at: %f, %f\n", float64(event.LatNano)/1e9, float64(event.LonNano)/1e9)
} else {
    fmt.Println("Entity not found")
}

Optional<GeoEvent> event = client.getLatest(entityId);

if (event.isPresent()) {
    GeoEvent e = event.get();
    System.out.printf("Last seen at: %f, %f%n",
        e.getLatNano() / 1e9, e.getLonNano() / 1e9);
} else {
    System.out.println("Entity not found");
}

geo_event_t event;
bool found = arch_get_latest(client, entity_id, &event);

if (found) {
    printf("Last seen at: %f, %f\n",
        (double)event.lat_nano / 1e9,
        (double)event.lon_nano / 1e9);
} else {
    printf("Entity not found\n");
}

const events = await client.getLatestBatch([entityId1, entityId2, entityId3])

console.log(`Found ${events.length} of 3 entities`)

for (const event of events) {
  console.log(`Entity ${event.entity_id}: ${event.lat_nano}, ${event.lon_nano}`)
}

events = client.get_latest_batch([entity_id1, entity_id2, entity_id3])

print(f"Found {len(events)} of 3 entities")

for event in events:
    print(f"Entity {event.entity_id}: {event.lat_nano}, {event.lon_nano}")

entityIDs := []types.Uint128{entityID1, entityID2, entityID3}

events, err := client.GetLatestBatch(entityIDs)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d of 3 entities\n", len(events))

List<BigInteger> entityIds = List.of(entityId1, entityId2, entityId3);

List<GeoEvent> events = client.getLatestBatch(entityIds);

System.out.println("Found " + events.size() + " of 3 entities");

uint128_t entity_ids[3] = {entity_id1, entity_id2, entity_id3};

void on_batch_result(void* ctx, const geo_event_t* events, size_t count) {
    printf("Found %zu of 3 entities\n", count);
}

arch_get_latest_batch(client, entity_ids, 3, on_batch_result, NULL);

const result = await client.deleteEntities([entityId1, entityId2])

console.log(`Deleted: ${result.deleted_count}`)
console.log(`Not found: ${result.not_found_count}`)

result = client.delete_entities([entity_id1, entity_id2])

print(f"Deleted: {result.deleted_count}")
print(f"Not found: {result.not_found_count}")

result, err := client.DeleteEntities([]types.Uint128{entityID1, entityID2})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Deleted: %d, Not found: %d\n", result.DeletedCount, result.NotFoundCount)

DeleteResult result = client.deleteEntities(List.of(entityId1, entityId2));

System.out.println("Deleted: " + result.getDeletedCount());
System.out.println("Not found: " + result.getNotFoundCount());

uint128_t entity_ids[2] = {entity_id1, entity_id2};

delete_result_t result;
arch_delete_entities(client, entity_ids, 2, &result);

printf("Deleted: %u, Not found: %u\n", result.deleted_count, result.not_found_count);