Skip to main content

Python Client for accessing the turbopuffer API

Project description

turbopuffer Python Client CI Test

The official Python client for accessing the turbopuffer API.

Usage

  1. Install the turbopuffer package and set your API key.
$ pip install turbopuffer

Or if you're able to run C binaries for JSON encoding, use:

$ pip install turbopuffer[fast]
  1. Start using the API
import turbopuffer as tpuf
tpuf.api_key = 'your-token'  # Alternatively: export=TURBOPUFFER_API_KEY=your-token
# Choose the best region for your data https://turbopuffer.com/docs/regions
tpuf.api_base_url = "https://gcp-us-east4.turbopuffer.com"

# Open a namespace
ns = tpuf.Namespace('hello_world')

# Read namespace metadata
if ns.exists():
    print(f'Namespace {ns.name} exists with {ns.dimensions()} dimensions and approximately {ns.approx_count()} vectors.')

# Upsert your dataset
ns.upsert(
    ids=[1, 2],
    vectors=[[0.1, 0.2], [0.3, 0.4]],
    attributes={'name': ['foo', 'foos']},
    distance_metric='cosine_distance',
)

# Alternatively, upsert using a row iterator
ns.upsert(
    {
        'id': id,
        'vector': [id/10, id/10],
        'attributes': {'name': 'food', 'num': 8}
    } for id in range(3, 10),
    distance_metric='cosine_distance',
)

# Query your dataset
vectors = ns.query(
    vector=[0.15, 0.22],
    distance_metric='cosine_distance',
    top_k=10,
    filters=['And', [
        ['name', 'Glob', 'foo*'],
        ['name', 'NotEq', 'food'],
    ]],
    include_attributes=['name'],
    include_vectors=True
)
print(vectors)
# [
#   VectorRow(id=2, vector=[0.30000001192092896, 0.4000000059604645], attributes={'name': 'foos'}, dist=0.001016080379486084),
#   VectorRow(id=1, vector=[0.10000000149011612, 0.20000000298023224], attributes={'name': 'foo'}, dist=0.009067952632904053)
# ]

# List all namespaces
namespaces = tpuf.namespaces()
print('Total namespaces:', len(namespaces))
for namespace in namespaces:
    print('Namespace', namespace.name, 'contains approximately', namespace.approx_count(),
            'vectors with', namespace.dimensions(), 'dimensions.')

# Delete vectors using the separate delete method
ns.delete([1, 2])

Endpoint Documentation

For more details on request parameters and query options, check the docs at https://turbopuffer.com/docs

Development

  1. poetry run pytest
  2. Bump version in turbopuffer/version.py and pyproject.toml
  3. poetry build
  4. poetry publish

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

turbopuffer-0.1.22.tar.gz (14.5 kB view details)

Uploaded Source

Built Distribution

turbopuffer-0.1.22-py3-none-any.whl (16.0 kB view details)

Uploaded Python 3

File details

Details for the file turbopuffer-0.1.22.tar.gz.

File metadata

  • Download URL: turbopuffer-0.1.22.tar.gz
  • Upload date:
  • Size: 14.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.2 CPython/3.12.1 Darwin/24.0.0

File hashes

Hashes for turbopuffer-0.1.22.tar.gz
Algorithm Hash digest
SHA256 ecd6e1a3b76880824583614a8625a58a1c4fda4ffea91786da7a9fe487545fdb
MD5 40da2b8f298f0708fff45dccadf9c959
BLAKE2b-256 8685b1be2beca13221e6d020c05de9aed402cf60c03c0b92f35423af1b9819bc

See more details on using hashes here.

File details

Details for the file turbopuffer-0.1.22-py3-none-any.whl.

File metadata

  • Download URL: turbopuffer-0.1.22-py3-none-any.whl
  • Upload date:
  • Size: 16.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.2 CPython/3.12.1 Darwin/24.0.0

File hashes

Hashes for turbopuffer-0.1.22-py3-none-any.whl
Algorithm Hash digest
SHA256 169e9edb7df468d4617700bd7bc1de3cd5826adb1bc36145487c76a01dfd347a
MD5 88f909dda44e50dbea7310e94314c980
BLAKE2b-256 50e72972ebb099cd28d1ac24ca7b308764ffd0ed30f8c1bb76a267bb7330e182

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page