Querying

Two ways to query data: a fluent query API with chainable methods, and raw SQL for full control. Both are available in the Python and TypeScript SDKs.

---

Fluent Query API

Python SDKTypeScript SDK

client.table(table) returns a chainable QueryBuilder. Call () or .execute() to run.

results = (
    client.table("videos")
        .select("id", "text", "start_time")
        .where("file_id = $1", "abc123")
        .order_by("start_time ASC")
        .limit(10)
)()

client.table(table) returns a chainable QueryBuilder. Call .execute() to run.

const results = await client.table("videos")
    .select("id", "text", "start_time")
    .where("file_id = $1", "abc123")
    .orderBy("start_time ASC")
    .limit(10)
    .execute();

QueryBuilder Methods

Python SDKTypeScript SDK

Method	Description	Example
.select(*cols)	Set columns (default *)	.select("id", "text")
.where(cond, *params)	Add WHERE (multiple = AND)	.where("id = $1", "abc")
.order_by(clause)	Add ORDER BY	.order_by("created_at DESC")
.limit(n)	Set LIMIT	.limit(10)
.offset(n)	Set OFFSET	.offset(20)
.execute() or ()	Run query, return list[dict]	.execute()

Method	Description	Example
.select(...cols)	Set columns (default *)	.select("id", "text")
.where(cond, ...params)	Add WHERE (multiple = AND)	.where("id = $1", "abc")
.orderBy(clause)	Add ORDER BY	.orderBy("created_at DESC")
.limit(n)	Set LIMIT	.limit(10)
.offset(n)	Set OFFSET	.offset(20)
.execute()	Run query, return Promise<QueryRow[]>	await .execute()

Examples

Python - Select columnsPython - Multiple WHEREPython - PaginationPython - AggregationTypeScript - Select columnsTypeScript - Multiple WHERETypeScript - PaginationTypeScript - Aggregation

results = client.table("documents").select("id", "text").limit(100)()

results = (
    client.table("videos")
        .select("id", "text", "start_time")
        .where("file_id = $1", "abc")
        .where("start_time > 60")
        .order_by("start_time")
        .limit(10)
)()

page_size = 20
page = 3
results = (
    client.table("documents")
        .select("id", "text")
        .order_by("id ASC")
        .limit(page_size)
        .offset(page_size * (page - 1))
)()

results = client.table("documents").select("COUNT(*) as total")()
print(f"Total rows: {results[0]['total']}")

const results = await client.table("documents")
    .select("id", "text")
    .limit(100)
    .execute();

const results = await client.table("videos")
    .select("id", "text", "start_time")
    .where("file_id = $1", "abc")
    .where("start_time > 60")
    .orderBy("start_time")
    .limit(10)
    .execute();

const pageSize = 20;
const page = 3;
const results = await client.table("documents")
    .select("id", "text")
    .orderBy("id ASC")
    .limit(pageSize)
    .offset(pageSize * (page - 1))
    .execute();

const results = await client.table("documents")
    .select("COUNT(*) as total")
    .execute();
console.log(`Total rows: ${results[0].total}`);

---

query()

Execute raw SQL and return all results as a list of dictionaries.

Python SDKTypeScript SDK

rows = client.query(sql, params=None)  # -> list[dict]

const rows = await client.query(sql, params?);  // -> QueryRow[]

Parameters

Python SDKTypeScript SDK

Parameter	Type	Required	Description
sql	str	yes	SQL query string. Use $1, $2, ... placeholders for parameterized values.
params	tuple	no	Parameter values corresponding to $1, $2, ... placeholders.

Parameter	Type	Required	Description
sql	string	yes	SQL query string. Use $1, $2, ... placeholders for parameterized values.
params	any[]	no	Parameter values corresponding to $1, $2, ... placeholders.

Examples

Python - Simple queryPython - Filtered queryPython - Vector searchPython - Hybrid searchPython - DELETE rowsPython - UPDATE rowsTypeScript - Simple queryTypeScript - Filtered queryTypeScript - Vector searchTypeScript - DELETE rowsTypeScript - UPDATE rows

rows = client.query("SELECT * FROM videos LIMIT 10")
for row in rows:
    print(row["id"], row["text"])

file_id = "abc123"
rows = client.query("SELECT * FROM documents WHERE file_id = $1", (file_id,))

query_emb = model.encode("search query").tolist()
emb_pg = "{" + ",".join(str(x) for x in query_emb) + "}"
results = client.query("""
    SELECT id, text, embedding <#> $1::float4[] AS score
    FROM embeddings
    ORDER BY score DESC LIMIT 10
""", (emb_pg,))

query_text = "neural networks"
query_emb = model.encode(query_text).tolist()
emb_pg = "{" + ",".join(str(x) for x in query_emb) + "}"
results = client.query("""
    SELECT id, text,
           (embedding, text)::deeplake_hybrid_record <#>
           deeplake_hybrid_record($1::float4[], $2, 0.7, 0.3) AS score
    FROM documents
    ORDER BY score DESC LIMIT 10
""", (emb_pg, query_text))

file_id = "old-file-123"
client.query("DELETE FROM documents WHERE file_id = $1", (file_id,))

client.query("""UPDATE documents SET metadata = '{"reviewed": true}'::jsonb WHERE id = 42""")

const rows = await client.query("SELECT * FROM videos LIMIT 10");
for (const row of rows) {
    console.log(row.id, row.text);
}

const fileId = "abc123";
const rows = await client.query(
    "SELECT * FROM documents WHERE file_id = $1", [fileId]
);

const queryEmb = await model.encode("search query");
const embPg = `{${queryEmb.join(",")}}`;
const results = await client.query(
    `SELECT id, text, embedding <#> $1::float4[] AS score
    FROM embeddings
    ORDER BY score DESC LIMIT 10`, [embPg]
);

const fileId = "old-file-123";
await client.query(
    "DELETE FROM documents WHERE file_id = $1", [fileId]
);

await client.query(
    `UPDATE documents SET metadata = '{"reviewed": true}'::jsonb WHERE id = 42`
);