Metadata-Version: 2.4
Name: originchaindb
Version: 0.1.24
Summary: OriginChainDB client for Python: SQL, graph, vector and full-text search over one HTTP API
Home-page: https://originchain.ai
Author: Silicoyn Technologies
Author-email: Silicoyn Technologies <support@originchain.ai>
License-Expression: MIT
Project-URL: Homepage, https://originchain.ai
Project-URL: Documentation, https://originchain.ai/docs
Keywords: originchain,originchaindb,database,sql,graph,vector,full-text search
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3<3.0.0,>=2.7.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# OriginChainDB for Python

The client for [OriginChainDB](https://originchain.ai): SQL, graph, vector and full-text search over one HTTP API.
It needs Python 3.10 or later.

## Install

```sh
pip install originchaindb
```

## Connect

You need your database's endpoint, its tenant id and an API key. All three are in the OriginChain console, in your
database's connection details.

```python
import os

import originchaindb as oc

config = oc.Configuration(host="https://your-database-endpoint", access_token=os.environ["ORIGINCHAIN_API_KEY"])
tenant = "your-tenant-id"
```

## SQL

```python
with oc.ApiClient(config) as client:
    result = oc.SqlApi(client).sql_exec(
        tenant, oc.SqlExecRequest(sql="SELECT id, name FROM people WHERE id = $1", params=["bob"]))
    print(result.columns, result.rows)
```

`params` binds `$1`, `$2`, … in order. A NULL cell is an absent key, so read cells by name against `columns`.

## Graph

```python
with oc.ApiClient(config) as client:
    # One-hop neighbours of a node along a relation: their primary keys.
    managers = oc.GraphApi(client).graph_neighbors(tenant, "public.people", "reports_to", "bob")
```

## Vector search

```python
with oc.ApiClient(config) as client:
    # The k stored vectors nearest to a query vector, best match first: each has .id and .score.
    nearest = oc.VectorApi(client).vector_topk(
        tenant, "doc_vectors", oc.VectorTopkRequest(query=[0.12, 0.98, 0.05], k=5, dim=3))
```

## Full-text search

```python
with oc.ApiClient(config) as client:
    # The ids of the documents whose `body` field matches.
    ids = oc.FtsApi(client).fts_search(tenant, "docs", "body", "vectors")
```

## Errors and request ids

A failed call raises `oc.ApiException`. Its `request_id` is the database's id for that request. Quote it when you
report a problem.

```python
try:
    with oc.ApiClient(config) as client:
        oc.SqlApi(client).sql_exec(tenant, oc.SqlExecRequest(sql="SELECT * FROM missing"))
except oc.ApiException as e:
    print(e.status, e.request_id)
```

## Diagnostics (off by default)

You can opt in to send call diagnostics to your own database. They contain the method, the path, the outcome, the
timing, the status and the request ids, and never SQL, parameters, row data, search text or error messages. Queued
diagnostics are sent at interpreter exit (for at most 2 seconds), or when you call `flush_diagnostics()`.

```python
oc.enable_diagnostics(config)
```

## More

Every endpoint is documented at [originchain.ai/docs](https://originchain.ai/docs).

## License

MIT
