Quickstart

Start a local Loams engine and query a collection through the native API. This walkthrough builds the engine from source. To run the whole Loams 0.1.0 stack from container images instead, follow Running Loams 0.1.0.

PrerequisitesCopy Anchor Link

• Rust installed through rustup. The repository pins the toolchain in rust-toolchain.toml.
• protoc (Protocol Buffers compiler) and curl.
• A supported native build environment. On Windows you also need the MSVC Build Tools and NASM; read the platform build guides for Windows and macOS prerequisites.

The first build compiles DataFusion, Lance, and Tantivy. On machines with less than 32 GB of RAM, add -j 4 to the Cargo command.

Build and startCopy Anchor Link

git clone --branch dev https://github.com/ostrium-labs/loams.git
cd loams
cargo run --release -p loams -- dev

loams dev keeps the local bucket and metastore under .loams/. Leave it running and open another terminal:

curl -i http://127.0.0.1:8080/ready

Readiness returns 200 once the metastore has a leader. The native API binds to loopback on port 8080; Qdrant (6333, 6334), Elasticsearch (9200), Flight SQL (8082) and Loams Live (7710) use separate loopback listeners. Live is in the default build and keeps its data under .loams/live/. Authentication is off by default, which the engine allows only on loopback. These shell examples use POSIX quoting; on Windows, use WSL or adapt quoting for PowerShell and call curl.exe.

Write and searchCopy Anchor Link

Create a collection, write documents and run a hybrid query. Every write returns a consistency token, and reads are strong by default, so they see the write at once.

curl -s localhost:8080/v1/namespaces/demo/collections -H 'content-type: application/json' -d '{
  "name": "kb",
  "schema": {
    "fields": [
      {"name": "body", "source_path": "body", "kind": "text", "indexed": true, "fast": false},
      {"name": "tenant", "source_path": "tenant", "kind": "keyword", "indexed": true, "fast": true}
    ],
    "vectors": [{"name": "embedding", "dim": 3, "distance": "cosine"}],
    "sparse_vectors": [], "dynamic": "ignore", "max_fields": 1000
  }
}'

curl -s localhost:8080/v1/namespaces/demo/collections/kb/documents -H 'content-type: application/json' -d '{"ops": [
  {"upsert": {"id": "doc-1", "source": {"body": "refund policy", "tenant": "a"}, "vectors": {"embedding": [1.0, 0.0, 0.0]}}},
  {"upsert": {"id": "doc-2", "source": {"body": "shipping times", "tenant": "a"}, "vectors": {"embedding": [0.9, 0.1, 0.0]}}},
  {"upsert": {"id": "doc-3", "source": {"body": "refund window", "tenant": "b"}, "vectors": {"embedding": [0.0, 0.0, 1.0]}}}
]}'

curl -s localhost:8080/v1/namespaces/demo/query -H 'content-type: application/json' -d '{
  "from": "collections.kb",
  "retrieve": [
    {"vector": {"field": "embedding", "query": [1.0, 0.0, 0.0], "k": 10}},
    {"text": {"field": "body", "query": "refund", "k": 10}}
  ],
  "filter": {"term": {"tenant": "a"}},
  "fuse": {"method": "rrf", "k": 60},
  "limit": 3
}'

The same query in SQL:

curl -s localhost:8080/v1/namespaces/demo/sql -H 'content-type: application/json' -d @- <<'JSON'
{"query": "SELECT _id, body, _score FROM rrf(vector_search('kb', [1.0, 0.0, 0.0], 'embedding', 10), text_search('kb', 'refund', 'body', 10)) WHERE tenant = 'a' LIMIT 3"}
JSON

Use your bucketCopy Anchor Link

For a single process backed by object storage:

cargo run --release -p loams -- standalone --bucket s3://my-bucket/loams --flight-sql-listen 127.0.0.1:8082

Configure credentials for the selected storage provider before starting. standalone defaults Flight SQL to 0.0.0.0:8082, and with authentication off the engine refuses to start on a non-loopback address, so either keep it on loopback as above or set LOAMS_AUTH_MODE. Metadata still needs the local data directory unless the optional TiKV metastore (--meta tikv://…) is configured. Use loams cluster --help for cluster roles and placement; check the CLI guide before deploying.

Next stepsCopy Anchor Link