> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Database SDK (TypeScript)

> The official zitejs client for calling the Zite Database API from your own Node.js or TypeScript code.

The `zitejs` package ships an official **`Zite` client** — a typed wrapper over the
[Database REST API](/api/overview) for use from your own Node.js or TypeScript code.

<Note>
  Don't confuse the two clients. **`Zite`** (below), imported from the package root, is for calling the
  Database API from *outside* Zite with an API key. The **`zite`** client from
  [`zitejs/db`](/framework/database-client) is the one generated *inside* a Zite app. Same data, different
  entry points.
</Note>

## Install

```bash theme={null}
npm install zitejs
```

## Initialize

Create a client with your API key (generate one in the
[Developer settings](https://app.zite.com/home/settings/developer)):

```typescript theme={null}
import { Zite } from 'zitejs';

const zite = new Zite(process.env.ZITE_API_KEY!);
```

## Records

The most common operations. Methods take positional ids (`databaseId`, `tableId`, `recordId`) followed by
the payload:

```typescript theme={null}
// Create
const ticket = await zite.record.create(databaseId, tableId, {
  subject: 'Printer is down',
  status: 'open',
});

// Get / update / delete by id
await zite.record.get(databaseId, tableId, ticket.id);
await zite.record.update(databaseId, tableId, ticket.id, { status: 'closed' });
await zite.record.delete(databaseId, tableId, ticket.id);

// List with filter, sort, and pagination
const { records, total, hasMore } = await zite.record.list(databaseId, tableId, {
  filter: { status: 'open' },
  sort: [{ field: 'createdAt', direction: 'desc' }],
  limit: 100,
  offset: 0,
});

// Bulk create (optionally upsert on matching fields) and bulk update
await zite.record.bulkCreate(databaseId, tableId, [{ email: 'a@b.com' }], ['email']);
await zite.record.bulkUpdate(databaseId, tableId, [{ recordId: ticket.id, status: 'closed' }]);
```

| Method              | Signature                                                                 |
| ------------------- | ------------------------------------------------------------------------- |
| `record.create`     | `(databaseId, tableId, record)`                                           |
| `record.get`        | `(databaseId, tableId, recordId)`                                         |
| `record.update`     | `(databaseId, tableId, recordId, record)`                                 |
| `record.delete`     | `(databaseId, tableId, recordId)`                                         |
| `record.list`       | `(databaseId, tableId, options?)` — `{ limit?, offset?, sort?, filter? }` |
| `record.bulkCreate` | `(databaseId, tableId, records, matchOn?)`                                |
| `record.bulkUpdate` | `(databaseId, tableId, records)` — each item includes `recordId`          |

## Schema: fields, tables, databases

Manage the schema with the same positional style:

```typescript theme={null}
// Databases
const db = await zite.database.create({ name: 'Helpdesk', tables: [/* … */] });
await zite.database.list();
await zite.database.get(databaseId);
await zite.database.delete(databaseId);

// Tables
await zite.table.create(databaseId, { name: 'Tickets', fields: [/* … */] });
await zite.table.update(databaseId, tableId, { name: 'SupportTickets' });
await zite.table.delete(databaseId, tableId);

// Fields
await zite.field.create(databaseId, tableId, { type: 'single_select', name: 'Status', template: { /* … */ } });
await zite.field.update(databaseId, tableId, fieldId, { name: 'State' });
await zite.field.delete(databaseId, tableId, fieldId);
```

See [Field types](/api/field-types) for the field `type` and `template` shapes.

## Aggregates and SQL

For counts, sums, group-bys, and read-only SQL over a base, use the Database API's
[aggregate](/api/records/aggregate-records) and SQL endpoints directly — these run in the database rather than
pulling rows to the client.

<Note>
  Finding your `databaseId` and `tableId`: open the database in the [dashboard](https://app.zite.com) and
  read them from the URL (`app.zite.com/database/{databaseId}/{tableId}/…`). See the
  [API overview](/api/overview#finding-database-and-table-ids).
</Note>