TablesDB API Reference - Docs

The TablesDB service allows you to create structured tables of rows, query and filter lists of rows, and manage an advanced set of read and write access permissions.

All data returned by the TablesDB service are represented as structured JSON rows.

The TablesDB service can contain multiple databases, each database can contain multiple tables. A table is a group of similarly structured rows. The accepted structure of rows is defined by table columns. The table columns help you ensure all your user-submitted data is validated and stored according to the table structure.

Using Appwrite permissions architecture, you can assign read or write access to each table or row in your project for either a specific user, team, user role, or even grant it with public access (any). You can learn more about how Appwrite handles permissions and access control.

Base URL

https://<REGION>.cloud.appwrite.io/v1

Create or update a row

Create or update a Row. Before using this route, you should create a new table resource using either a server integration API or directly from your database console.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID.
- rowId string
  required
  
  Row ID.
- data object
  
  Row data as JSON object. Include all required columns of the row to be created or updated.
- permissions array
  
  An array of permissions strings. By default, the current permissions are inherited. Learn more about permissions.
Response
- 201 application/json
  
  Row
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PUT /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.upsertRow({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    rowId: '<ROW_ID>',
    data: {}, // optional
    permissions: ["read("any")"] // optional
});

console.log(result);

Get row

Get a row by its unique ID. This endpoint response returns a JSON object with the row data.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID. You can create a new table using the Database service server integration.
- rowId string
  required
  
  Row ID.
- queries array
  
  Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long.
Response
- 200 application/json
  
  Row

Endpoint

GET /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.getRow({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    rowId: '<ROW_ID>',
    queries: [] // optional
});

console.log(result);

List rows

Get a list of all the user's rows in a given table. You can use the query params to filter your results.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID. You can create a new table using the TableDB service server integration.
- queries array
  
  Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long.
Response
- 200 application/json
  
  Rows List

Endpoint

GET /tablesdb/{databaseId}/tables/{tableId}/rows

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.listRows({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    queries: [] // optional
});

console.log(result);

Update row

Update a row by its unique ID. Using the patch method you can pass only specific fields that will get updated.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID.
- rowId string
  required
  
  Row ID.
- data object
  
  Row data as JSON object. Include only columns and value pairs to be updated.
- permissions array
  
  An array of permissions strings. By default, the current permissions are inherited. Learn more about permissions.
Response
- 200 application/json
  
  Row
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.updateRow({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    rowId: '<ROW_ID>',
    data: {}, // optional
    permissions: ["read("any")"] // optional
});

console.log(result);

Delete row

Delete a row by its unique ID.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID. You can create a new table using the Database service server integration.
- rowId string
  required
  
  Row ID.
Response
- 204 no content
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 60 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	60 requests	IP + METHOD + URL + USER ID

Endpoint

DELETE /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.deleteRow({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    rowId: '<ROW_ID>'
});

console.log(result);

Decrement row column

Decrement a specific column of a row by a given value.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID.
- rowId string
  required
  
  Row ID.
- column string
  required
  
  Column key.
- value number
  
  Value to increment the column by. The value must be a number.
- min number
  
  Minimum value for the column. If the current value is lesser than this value, an exception will be thrown.
Response
- 200 application/json
  
  Row
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/decrement

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.decrementRowColumn({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    rowId: '<ROW_ID>',
    column: '',
    value: null, // optional
    min: null // optional
});

console.log(result);

Increment row column

Increment a specific column of a row by a given value.

Request
- databaseId string
  required
  
  Database ID.
- tableId string
  required
  
  Table ID.
- rowId string
  required
  
  Row ID.
- column string
  required
  
  Column key.
- value number
  
  Value to increment the column by. The value must be a number.
- max number
  
  Maximum value for the column. If the current value is greater than this value, an error will be thrown.
Response
- 200 application/json
  
  Row
Rate limits

This endpoint is rate limited. You can only make a limited number of request to his endpoint within a specific time frame.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/increment

Web

import { Client, TablesDB } from "appwrite";

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>'); // Your project ID

const tablesDB = new TablesDB(client);

const result = await tablesDB.incrementRowColumn({
    databaseId: '<DATABASE_ID>',
    tableId: '<TABLE_ID>',
    rowId: '<ROW_ID>',
    column: '',
    value: null, // optional
    max: null // optional
});

console.log(result);

Recommended