# KV Store: Batch Operations

**Page:** api/sqlite/kv-batch

[Download Raw Markdown](./api/sqlite/kv-batch.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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.


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.

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

### Response



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


```json
{
  "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 |


```json
{
  "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

```javascript
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.

```json
{
  "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



```json
{
  "count": 3
}
```


```json
{
  "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 |


```json
{
  "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

```javascript
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.

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

### Response



```json
{
  "count": 3
}
```


```json
{
  "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 |


```json
{
  "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

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