Batch operations let you read, write, or delete up to 100 keys in a single request, reducing round-trips when working with large datasets. All batch endpoints accept a JSON body describing the keys or items to process and execute the work in a single transaction.

Note

All three endpoints share the same db and table query parameters and the same error code surface. The body shape is an object; the specific structure (keys array for get/delete, items array for set) follows the endpoint’s purpose.

Batch Get Multiple Keys

Retrieve values for multiple keys in a single request (max 100 keys).

POST /api/v1/sqlite/kv/batch/get

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"

Request Body

Send a JSON object containing the keys to retrieve. The body is an unconstrained object — supply a keys array of string identifiers.

{
  "keys": ["user:1", "user:2", "settings:theme"]
}

Response

200

{
  "values": {
    "user:1": { "name": "Alice", "email": "alice@example.com" },
    "user:2": { "name": "Bob", "email": "bob@example.com" },
    "settings:theme": "dark"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

Error Code	Title	Description	Resolution
INVALID_DB_PATH	Invalid database path	The provided database path is invalid or inaccessible	Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db)
INVALID_PARAMETERS	Invalid request parameters	One or more request parameters are invalid or malformed	Check parameter types and values against the API specification
INVALID_SQLITE_HEADER	Not a valid SQLite database	The file exists but is not a valid SQLite database	Ensure the file is a valid SQLite database with proper header
PATH_IS_DIRECTORY	Path is a directory	Expected a .db file but got a directory (use table parameter for directory mode)	Use a .db file path or add table parameter for directory mode KV store

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed"
}

Error Code	Title	Description	Resolution
DATABASE_ERROR	Database operation failed	An internal database error occurred	Check server logs for details. Database may be corrupted or locked.
FILE_SYSTEM_ERROR	File system error	Failed to read or write filesystem in directory mode	Check file permissions and disk space

SDK Usage

const result = await client.sqlite.kvStore.batchGet({
  db: '/hoody/databases/app.db',
  table: 'kv_store',
  data: {
    keys: ['user:1', 'user:2', 'settings:theme']
  }
});

---

Batch Set Multiple Keys

Store values for multiple keys in a single transaction (max 100 items).

POST /api/v1/sqlite/kv/batch/set

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"

Request Body

Send a JSON object containing the items to store. The body is an unconstrained object — supply an items array of key/value pairs.

{
  "items": [
    { "key": "user:1", "value": { "name": "Alice", "email": "alice@example.com" } },
    { "key": "user:2", "value": { "name": "Bob", "email": "bob@example.com" } },
    { "key": "settings:theme", "value": "dark" }
  ]
}

Response

200

{
  "count": 3
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

Error Code	Title	Description	Resolution
INVALID_DB_PATH	Invalid database path	The provided database path is invalid or inaccessible	Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db)
INVALID_PARAMETERS	Invalid request parameters	One or more request parameters are invalid or malformed	Check parameter types and values against the API specification
INVALID_SQLITE_HEADER	Not a valid SQLite database	The file exists but is not a valid SQLite database	Ensure the file is a valid SQLite database with proper header
PATH_IS_DIRECTORY	Path is a directory	Expected a .db file but got a directory (use table parameter for directory mode)	Use a .db file path or add table parameter for directory mode KV store

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed"
}

Error Code	Title	Description	Resolution
DATABASE_ERROR	Database operation failed	An internal database error occurred	Check server logs for details. Database may be corrupted or locked.
FILE_SYSTEM_ERROR	File system error	Failed to read or write filesystem in directory mode	Check file permissions and disk space

SDK Usage

const result = await client.sqlite.kvStore.batchSet({
  db: '/hoody/databases/app.db',
  table: 'kv_store',
  data: {
    items: [
      { key: 'user:1', value: { name: 'Alice', email: 'alice@example.com' } },
      { key: 'user:2', value: { name: 'Bob', email: 'bob@example.com' } }
    ]
  }
});

---

Batch Delete Multiple Keys

Delete multiple keys in a single transaction (max 100 keys).

POST /api/v1/sqlite/kv/batch/delete

Parameters

Name	In	Type	Required	Description
db	query	string	Yes	Database file path
table	query	string	No	Custom table name. Default: "kv_store"

Request Body

Send a JSON object containing the keys to delete. The body is an unconstrained object — supply a keys array of string identifiers.

{
  "keys": ["user:1", "user:2", "settings:theme"]
}

Response

200

{
  "count": 3
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

Error Code	Title	Description	Resolution
INVALID_DB_PATH	Invalid database path	The provided database path is invalid or inaccessible	Provide a valid absolute path, or use bare name / ./name shorthand (resolved to /hoody/databases/*.db)
INVALID_PARAMETERS	Invalid request parameters	One or more request parameters are invalid or malformed	Check parameter types and values against the API specification
INVALID_SQLITE_HEADER	Not a valid SQLite database	The file exists but is not a valid SQLite database	Ensure the file is a valid SQLite database with proper header
PATH_IS_DIRECTORY	Path is a directory	Expected a .db file but got a directory (use table parameter for directory mode)	Use a .db file path or add table parameter for directory mode KV store

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Database operation failed"
}

Error Code	Title	Description	Resolution
DATABASE_ERROR	Database operation failed	An internal database error occurred	Check server logs for details. Database may be corrupted or locked.
FILE_SYSTEM_ERROR	File system error	Failed to read or write filesystem in directory mode	Check file permissions and disk space

SDK Usage

const result = await client.sqlite.kvStore.batchDelete({
  db: '/hoody/databases/app.db',
  table: 'kv_store',
  data: {
    keys: ['user:1', 'user:2', 'settings:theme']
  }
});