Python

pip install tachyon-sdk

Requires Python 3.8+.

Quickstart

from tachyon_sdk import Tachyon

client = Tachyon(url="http://localhost:8108", api_key="my-admin-key")

client.collections.create({
    "name": "products",
    "fields": [
        {"name": "title", "type": "text"},
        {"name": "brand", "type": "keyword", "facet": True},
        {"name": "price", "type": "int", "filter": True, "sort": True},
    ],
})

client.collection("products").documents.index([
    {"id": "1", "title": "Wireless Mouse", "brand": "Logitech", "price": 2999},
    {"id": "2", "title": "Mechanical Keyboard", "brand": "Razer", "price": 8999},
])

results = client.collection("products").search(q="wireless mouse")
for hit in results["hits"]:
    print(hit["document"]["title"], hit["text_match"])

Client options

Tachyon(
    url="http://localhost:8108",  # or host="localhost", port=8108, protocol="http"
    api_key="...",                # admin key (read/write) or search key (read-only)
    timeout=15.0,                 # seconds
    headers={"X-Custom": "value"},
    session=None,                 # pass your own requests.Session to share pooling
)

Collections

client.collections.create(schema)   # POST   /collections
client.collections.list()           # GET    /collections
client.collections.retrieve(name)   # GET    /collections/{name}
client.collections.delete(name)     # DELETE /collections/{name}

Documents

collection = client.collection("products")

collection.documents.index(doc_or_list)  # POST   /collections/{name}/documents  (upsert by id)
collection.documents.retrieve(doc_id)    # GET    /collections/{name}/documents/{id}
collection.documents.delete(doc_id)      # DELETE /collections/{name}/documents/{id}

index() always succeeds at the HTTP level even if individual documents are rejected — check num_failed and results on the response.

Search

collection.search(
    q="wireless mouse",
    query_by=["title", "description"],
    filter="brand:=Logitech && price:<5000",
    sort="_text_match:desc,price:asc",
    facet=["brand", "year"],
    limit=20,
    offset=0,
    prefix=True,
    typo_tolerance=True,
    match_mode="all",  # or "any"
)

query_by and facet accept either a comma-separated string or a list of field names. Every parameter is optional keyword-only, except q.

found_is_exact on the response is False once block-max WAND pruning has skipped part of a term's postings for a broad query — at that point found and facet counts are a lower bound, not an exact count.

Autocomplete

collection.suggest(q="wir", limit=5)

Analytics

client.analytics.top(collection="products", limit=10)
client.analytics.zero_results(collection="products")
client.analytics.latency()

Analytics are in-memory only and reset when the server restarts.

Operations

client.health()   # GET /health — no API key required
client.metrics()  # GET /metrics — Prometheus exposition format, returned as text

Errors

Every non-2xx response raises a TachyonError subclass carrying the server's stable code and the HTTP status:

from tachyon_sdk import TachyonError, TachyonNotFoundError

try:
    client.collections.retrieve("does-not-exist")
except TachyonNotFoundError as e:
    print(e.code, e.status, e.message)  # collection_not_found 404 ...
except TachyonError as e:
    ...  # any other API error

Class	Status	Codes
`TachyonRequestError`	400	`invalid_schema`, `invalid_document`, `invalid_query`, `invalid_json`
`TachyonAuthenticationError`	401	`unauthorized`
`TachyonAuthorizationError`	403	`forbidden`
`TachyonNotFoundError`	404	`collection_not_found`, `document_not_found`
`TachyonConflictError`	409	`collection_exists`
`TachyonServerError`	5xx	`corrupt_data`, `io_error`, `internal_error`

Network failures and timeouts raise TachyonConnectionError / TachyonTimeoutError instead, since there's no server response to read a code from.

Types

Request and response shapes are TypedDicts in tachyon_sdk.types — plain dicts at runtime, typed for editor/mypy support: CollectionSchema, CollectionInfo, FieldSchema, TachyonDocument, SearchResponse, SuggestResponse, AnalyticsQueriesResponse, AnalyticsLatencyResponse, HealthResponse, and friends.

Source

python/ in the tachyon-sdk repo, including the mocked unit suite and a separate integration suite that runs against a real server.

On this page