Skip to main content

tachyon-sdk (Python)

Official Python client for Tachyon, the typo-tolerant full-text search engine.

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.

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. See the Known limitations section of the main README.

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.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
mypy tachyon_sdk

Integration tests

Plain pytest only runs the mocked unit suite (integration tests are marker-excluded by default). A second suite in tests/integration/ exercises every functional path — collections, documents, search (filters, sort, facets, pagination, prefix, typo tolerance, match mode, phrases), suggest, analytics, auth, and error paths — against a real, running Tachyon server:

docker run -d -p 8108:8108 \
  -e TACHYON_ADMIN_KEY=admin-key -e TACHYON_SEARCH_KEY=search-key \
  adikeshri/tachyon

pytest -m integration

It points at http://localhost:8108 by default; override with the TACHYON_URL, TACHYON_ADMIN_KEY, TACHYON_SEARCH_KEY environment variables. Every test cleans up the collections it creates, even on failure.

License

Apache 2.0. See LICENSE.

Metadata

Release files for tachyon-sdk 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tachyon-sdk 1.0.0
File Size Uploaded Provenance Actions
tachyon_sdk-1.0.0.tar.gz 15.5 kB Without provenance Details for tachyon_sdk-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tachyon-sdk 1.0.0
File Interpreter ABI Platform Actions
tachyon_sdk-1.0.0-py3-none-any.whl Python 3 none any Details for tachyon_sdk-1.0.0-py3-none-any.whl

Total release size: 27.7 kB

Release files / tachyon_sdk-1.0.0.tar.gz

Download URL tachyon_sdk-1.0.0.tar.gz
Size 15.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c7d222a149946c1440e9eb80c481153a381e8e20ba0d8d9b2c0a9bdea35a15ab
BLAKE2b-256 checksum
How to use checksums
b782d3595f4ad2ab688b5005eea96650e4c8fff12c584d5e7db2726ad92ef7a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / tachyon_sdk-1.0.0-py3-none-any.whl

Download URL tachyon_sdk-1.0.0-py3-none-any.whl
Size 12.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8e44b57a8bf95c7744c08540c2f59ab737abedb6861a2e50b0979b12baa37677
BLAKE2b-256 checksum
How to use checksums
eac046258b4796149851761aa7539c2166ed2ed0805c9e1eb11e0468bbf6ffa6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for tachyon-sdk 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page