SDK Client¶

The Client class is the main entry point for the DeepLake SDK.

Python SDKTypeScript SDK

pip install deeplake

npm install deeplake

Client()¶

Create a new client instance.

Python SDKTypeScript SDK

from deeplake import Client

client = Client(
    token=os.environ["DEEPLAKE_API_KEY"],
    workspace_id=os.environ["DEEPLAKE_WORKSPACE"],
)

const { ManagedClient } = require("deeplake");
const { initializeWasm } = require("deeplake/wasm");

await initializeWasm();

const client = new ManagedClient({
    token: process.env.DEEPLAKE_API_KEY,
    workspaceId: process.env.DEEPLAKE_WORKSPACE,
});
await client.applyStorageCreds("readwrite");

TypeScript: WASM initialization

The TypeScript SDK requires await initializeWasm() before creating a client. This loads the WebAssembly module that powers the C++ core. Call it once at startup. The applyStorageCreds("readwrite") call injects cloud storage credentials into the WASM engine and resolves the orgId - required for dataset writes.

Parameters¶

Python SDKTypeScript SDK

Parameter	Type	Required	Description
`token`	`str`	No	DeepLake API token. Falls back to `DEEPLAKE_API_KEY` environment variable.
`workspace_id`	`str`	No	Target workspace identifier. Falls back to `DEEPLAKE_WORKSPACE` environment variable.
`api_url`	`str`	No	API server URL. Falls back to `DEEPLAKE_API_URL` environment variable.

Parameter	Type	Required	Description
`token`	`string`	Yes	DeepLake API token.
`workspaceId`	`string`	No	Target workspace identifier. Default: `"default"`.
`apiUrl`	`string`	No	API server URL. Default: `https://api.deeplake.ai`.

org_id is always extracted from the token JWT claims automatically. If the token does not contain an OrgID claim, the client falls back to fetching it from the /me API endpoint.

Dataset root path is fetched from the PostgreSQL GUC deeplake.root_path automatically. No manual configuration is needed.

Examples¶

Python - BasicPython - Custom API URLPython - From environment variablesTypeScript - BasicTypeScript - Custom API URL

import os
from deeplake import Client

client = Client(
    token=os.environ["DEEPLAKE_API_KEY"],
    workspace_id=os.environ["DEEPLAKE_WORKSPACE"],
)

client = Client(
    token=os.environ["DEEPLAKE_API_KEY"],
    workspace_id=os.environ["DEEPLAKE_WORKSPACE"],
    api_url="https://custom-api.example.com",
)

# With DEEPLAKE_API_KEY and DEEPLAKE_WORKSPACE exported, no args needed
client = Client()
client.ingest("table", {"path": ["file.txt"]}, schema={"path": "FILE"})

const { ManagedClient } = require("deeplake");
const { initializeWasm } = require("deeplake/wasm");

await initializeWasm();

const client = new ManagedClient({
    token: process.env.DEEPLAKE_API_KEY,
    workspaceId: process.env.DEEPLAKE_WORKSPACE,
});
await client.applyStorageCreds("readwrite");

const client = new ManagedClient({
    token: process.env.DEEPLAKE_API_KEY,
    workspaceId: process.env.DEEPLAKE_WORKSPACE,
    apiUrl: "https://custom-api.example.com",
});
await client.applyStorageCreds("readwrite");

Environment Variables¶

Variable	Description	Default
`DEEPLAKE_API_KEY`	API token	--
`DEEPLAKE_WORKSPACE`	Workspace ID	--
`DEEPLAKE_API_URL`	API base URL	`https://api.deeplake.ai`

list_tables()¶

Returns the names of all tables in the current workspace.

Python SDKTypeScript SDK

tables = client.list_tables()  # -> list[str]

const tables = await client.listTables();  // -> string[]

Examples¶

Python - List allPython - Check if table existsTypeScript - List allTypeScript - Check if table exists

tables = client.list_tables()
print(tables)  # ["videos", "documents", "embeddings"]

if "documents" in client.list_tables():
    print("Table exists")
else:
    print("Table not found")

const tables = await client.listTables();
console.log(tables);  // ["videos", "documents", "embeddings"]

const tables = await client.listTables();
if (tables.includes("documents")) {
    console.log("Table exists");
} else {
    console.log("Table not found");
}

drop_table()¶

Drops (deletes) a table from the workspace.

Python SDKTypeScript SDK

client.drop_table(table_name, if_exists=True)

await client.dropTable(tableName, ifExists);  // ifExists defaults to true

Parameters¶

Python SDKTypeScript SDK

Parameter	Type	Required	Description
`table_name`	`str`	yes	Name of the table to drop.
`if_exists`	`bool`	no	If `True`, do not raise an error if the table is absent. Default: `True`

Parameter	Type	Required	Description
`tableName`	`string`	yes	Name of the table to drop.
`ifExists`	`boolean`	no	If `true`, do not throw if the table is absent. Default: `true`

Examples¶

Python - Basic dropPython - Check after dropTypeScript - Basic dropTypeScript - Check after drop

client.drop_table("old_data")

client.drop_table("old_data")
remaining = client.list_tables()
print(f"Remaining tables: {remaining}")

await client.dropTable("old_data");

await client.dropTable("old_data");
const remaining = await client.listTables();
console.log(`Remaining tables: ${remaining}`);

open_table()¶

Open a managed table for direct dataset access. Bypasses PostgreSQL and returns the native dataset object.

Python SDKTypeScript SDK

ds = client.open_table(table_name)  # -> deeplake.Dataset

const ds = await client.openTable(tableName);  // -> dataset handle

Parameters¶

Parameter	Type	Required	Description
`table_name` / `tableName`	`str` / `string`	yes	Table name (must have been created via `ingest()`).

When to use: Training loops, batch iteration, PyTorch/TensorFlow DataLoaders (Python), or direct field-level reads/writes (TypeScript).

Python: Batch Iteration & DataLoaders¶

ds = client.open_table("videos")
for batch in ds.batches(32):
    train(batch)

PyTorchTensorFlow

from torch.utils.data import DataLoader

ds = client.open_table("training_data")
loader = DataLoader(ds.pytorch(), batch_size=32, shuffle=True, num_workers=4)

for batch in loader:
    images, labels = batch["image"], batch["label"]
    loss = model(images, labels)
    loss.backward()

import tensorflow as tf

ds = client.open_table("training_data")
tf_ds = ds.tensorflow().batch(32).prefetch(tf.data.AUTOTUNE)

model.fit(tf_ds, epochs=10)

Python: TQL Filtering¶

WHERE filterLabel filterComplex condition

ds = client.open_table("embeddings")
view = ds.query("SELECT * WHERE label = 'cat'")
for batch in view.batches(16):
    process(batch)

ds = client.open_table("images")
cats_only = ds.query("SELECT * WHERE category IN ('cat', 'kitten')")
loader = DataLoader(cats_only.pytorch(), batch_size=32)

ds = client.open_table("training_data")
view = ds.query("""
    SELECT * WHERE split = 'train'
    AND confidence > 0.9
    ORDER BY created_at DESC
    LIMIT 10000
""")

TypeScript: Direct Data Access¶

The TypeScript SDK provides field-level read/write methods via the client:

Read fieldsWrite fields

// Get a single field value
const text = await client.getField("my_table", 0, "text");

// Get an entire row (selected columns)
const row = await client.getRow("my_table", 0, ["text", "score", "count"]);
// -> { text: "hello world", score: 0.9, count: 10 }

// Get a column slice
const scores = await client.getColumnData("my_table", "score", 0, 3);
// -> [0.9, 0.8, 0.7]

// Get row count
const numRows = await client.getNumRows("my_table");

// Update a single field (auto-commits)
await client.setField("my_table", 0, "score", 0.95);

// Update multiple fields in a row (auto-commits)
await client.setRow("my_table", 2, { score: 0.99, count: 42 });