dataoil

The Data Oil client for Python. One statement over rows, vectors, keywords and relationships, streamed as NDJSON, with the two tenancy headers, typed errors and the retry a lost race needs built in. Standard library only; Python 3.10+.

pip install dataoil
pip install "dataoil[langchain]"     # + a LangChain retriever
pip install "dataoil[llamaindex]"    # + a LlamaIndex retriever

Sixty seconds

from dataoil import DataOilClient

client = DataOilClient("https://acme.dataoil.tech", "bookshop", username="your-account", password="...")
# or, with an API key:  DataOilClient("https://acme.dataoil.tech", "bookshop", token="dot_...")

client.statement("INSERT INTO Book SET isbn = :isbn, title = :title", {"isbn": "978-py", "title": "From Python"})

for row in client.statement("SELECT isbn, title FROM Book ORDER BY isbn"):
    print(row["isbn"], row["title"])

# A large scan streams, and follows the cursor across pages.
for row in client.query("SELECT FROM Report WHERE filedAt > :since", {"since": "2026-01-01"}, page_size=2000):
    handle(row)

# One statement over keywords, meaning and a column.
hits = client.statement("""
    SELECT title, VECTOR_DISTANCE(embedding, EMBED(:q), 'cosine') AS distance, $score AS keywordScore
    FROM Report
    WHERE SEARCH_INDEX('Report[body]', :q) = true AND filedAt > date('2026-01-01')
    ORDER BY distance LIMIT 10
""", {"q": "casing failure"})

What it does for you

Retrievers: the AI project that does not start with an export

from dataoil import DataOilClient, Search
from dataoil.langchain import DataOilRetriever          # or dataoil.llamaindex

client = DataOilClient("https://acme.dataoil.tech", "kb", token="dot_...")
search = Search(client, "customer_docs", embed=my_embedding_model)   # the same model the ingestion used
retriever = DataOilRetriever(search=search)

docs = retriever.invoke("what changed in the March release?")

Search asks the database for the passages nearest a question: by keyword through the full-text index (SEARCH_INDEX, ranked by BM25), by meaning through the vector index (vector.neighbors), or both fused by rank (mode="hybrid", the default when an embed function is given). Every hit carries the record it came from, so a chain cites the row rather than a copy of it - and every fence the engine applies to a statement applies here, because a retrieval is a statement. Nothing is copied out.

The rest of the surface

record = client.create("Book", {"isbn": "1", "title": "A"})     # {rid, type, properties}
client.get(record["rid"]); client.delete(record["rid"])
client.batch([BatchOperation("INSERT INTO Book SET isbn = :i", {"i": "1"}), BatchOperation("INSERT INTO Book SET isbn = :i", {"i": "2"})])
tx = client.begin(); client.statement("INSERT INTO Book SET isbn = '3'", transaction=tx); client.commit(tx)   # or rollback
client.schema(); client.schema_narrative()
client.mint_token("the reporting job", rights=["read"], lifetime_seconds=30 * 86400)
client.ask("which reports mention casing?", rows, statement=sql)     # the tenant's own model, sent only the rows you read
client.request("GET", "/api/v2/databases/bookshop/statistics")

ca_file= names a certificate to trust for a deployment on its own authority.

Tests

pytest runs 28 checks against a stub that answers exactly what the engine answers - NDJSON with its trailer, problem documents with X-Retryable, a 429 with Retry-After. Set DATAOIL_URL, DATAOIL_DATABASE and a credential (and DATAOIL_CA for a self-signed deployment) and one more creates a type, writes, streams, searches, refuses and drops against a running engine.

The reference manual is at https://documents.dataoil.tech/tenant/.

Source and licensing

Questions, issues and releases: https://documents.dataoil.tech/tenant/ and info@dataoil.tech. The packages are published to the public registries as compiled packages; their source is not published.

This library is proprietary and licensed only for legitimate use with Data Oil, under the Data Oil Software Licence (see LICENSE): copying, modifying, redistributing or reverse engineering it, and any attack on or unauthorised access to the platform, are prohibited. Data Oil itself is a commercial service of MaxDragon Technology, and using it needs a credential issued under the Data Oil customer agreement. The library grants no right to the service, and the service applies its own rights, budgets and audit to every credential. The NOTICE file in the package has the full statement, the trademark note and the third-party components.