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

# Customer DB: Query Customer Db

> Run SQL against your workspace's customer database to read enriched records or write to your own tables, and get rows back.

Run SQL against your workspace's customer database to read enriched records or write to your own tables, and get rows back.

> [!NOTE]
>
> Tool ID: `query_customer_db`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'query_customer_db',
  {
    "sql": "SELECT * FROM companies LIMIT 10"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute query_customer_db --input '{
  "sql": "SELECT * FROM companies LIMIT 10"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "command": "example",
  "row_count": 1,
  "row_count_returned": 123,
  "truncated": true,
  "columns": [
    {
      "name": "Example",
      "table_id": 1,
      "data_type_id": 1
    }
  ],
  "rows": [
    {}
  ]
}
```

Use `deepline describe query_customer_db --json` for the latest machine-readable contract.

## Input reference

Query the workspace customer database through Deepline APIs and return structured rows. This is the agent-safe SQL surface: read permitted schemas, but write only schema-qualified customer-managed targets outside protected Deepline schemas. CREATE TABLE, INSERT, UPDATE, DELETE, ALTER, DROP, TRUNCATE, and CREATE INDEX require schema-qualified targets.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.operation_key` | `string` | No | — | Stable identity for one intended SQL operation. The result and statement commit atomically. Reuse this key only to recover that operation. A changed SQL or row limit is rejected. Non-transactional statements cannot use it. Minimum length: 1. Maximum length: 512. |
| `payload.result_mode` | `"rows" \| "dataset"` | No | — | rows returns one bounded scalar result. dataset retains live paging. Omission preserves the historical behavior. Allowed: `rows`, `dataset`. |
| `payload.sql` | `string` | Yes | — | One SQL statement for the workspace customer DB. Use SELECT/EXPLAIN/read-only WITH to inspect permitted schemas. Writes and DDL must target a schema-qualified customer-managed table or schema, for example CREATE TABLE analytics.agent\_notes (...). Protected Deepline schemas are read-only, and unqualified CREATE TABLE blocked (...) is rejected. Minimum length: 1. |
| `payload.max_rows` | `integer` | No | — | Maximum rows to return in the response payload. Default 1000. This caps returned rows only. It does not restrict SQL shape, aggregates, GROUP BY, or CTE usage. Minimum: 1. Maximum: 1000. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Query the workspace customer database through Deepline APIs and return structured rows. This is the agent-safe SQL surface: read permitted schemas, but write only schema-qualified customer-managed targets outside protected Deepline schemas. CREATE TABLE, INSERT, UPDATE, DELETE, ALTER, DROP, TRUNCATE, and CREATE INDEX require schema-qualified targets.",
    "properties": {
      "operation_key": {
        "type": "string",
        "description": "Stable identity for one intended SQL operation. The result and statement commit atomically. Reuse this key only to recover that operation; a changed SQL or row limit is rejected. Non-transactional statements cannot use it.",
        "minLength": 1,
        "maxLength": 512
      },
      "result_mode": {
        "type": "string",
        "description": "rows returns one bounded scalar result; dataset retains live paging. Omission preserves the historical behavior.",
        "enum": [
          "rows",
          "dataset"
        ]
      },
      "sql": {
        "type": "string",
        "description": "One SQL statement for the workspace customer DB. Use SELECT/EXPLAIN/read-only WITH to inspect permitted schemas. Writes and DDL must target a schema-qualified customer-managed table or schema, for example CREATE TABLE analytics.agent_notes (...). Protected Deepline schemas are read-only, and unqualified CREATE TABLE blocked (...) is rejected.",
        "minLength": 1
      },
      "max_rows": {
        "type": "integer",
        "description": "Maximum rows to return in the response payload. Default 1000. This caps returned rows only; it does not restrict SQL shape, aggregates, GROUP BY, or CTE usage.",
        "minimum": 1,
        "maximum": 1000
      }
    },
    "required": [
      "sql"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.command` | `string` | Yes | — | — |
| `result.row_count` | `integer` | Yes | — | — |
| `result.row_count_returned` | `integer` | Yes | — | — |
| `result.operation` | `object` | No | — | — |
| `result.operation.operation_key` | `string` | Yes | — | Minimum length: 1. Maximum length: 512. |
| `result.operation.completed_at_ms` | `integer` | Yes | — | Minimum: 0. |
| `result.operation.source` | `"executed" \| "operation_recovery"` | Yes | — | Allowed: `executed`, `operation_recovery`. |
| `result.truncated` | `boolean` | Yes | — | — |
| `result.columns` | `array` | Yes | — | — |
| `result.columns[].name` | `string` | Yes | — | — |
| `result.columns[].table_id` | `integer \| null` | Yes | — | — |
| `result.columns[].data_type_id` | `integer \| null` | Yes | — | — |
| `result.rows` | `array` | Yes | — | — |
| `result.dataset` | `object` | No | — | — |
| `result.dataset.kind` | `"customer_db_query"` | Yes | — | Allowed: `customer_db_query`. |
| `result.dataset.total_rows` | `integer` | Yes | — | — |
| `result.dataset.returned_limit` | `integer` | Yes | — | — |
| `result.dataset.offset` | `integer` | Yes | — | — |
| `result.dataset.page_size` | `integer` | Yes | — | — |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "properties": {
      "command": {
        "type": "string"
      },
      "row_count": {
        "type": [
          "integer",
          "null"
        ]
      },
      "row_count_returned": {
        "type": "integer"
      },
      "operation": {
        "type": "object",
        "properties": {
          "operation_key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "completed_at_ms": {
            "type": "integer",
            "minimum": 0
          },
          "source": {
            "type": "string",
            "enum": [
              "executed",
              "operation_recovery"
            ]
          }
        },
        "required": [
          "operation_key",
          "completed_at_ms",
          "source"
        ],
        "additionalProperties": false
      },
      "truncated": {
        "type": "boolean"
      },
      "columns": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "table_id": {
              "type": [
                "integer",
                "null"
              ]
            },
            "data_type_id": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "required": [
            "name",
            "table_id",
            "data_type_id"
          ],
          "additionalProperties": false
        }
      },
      "rows": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "dataset": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "customer_db_query"
            ]
          },
          "total_rows": {
            "type": "integer"
          },
          "returned_limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          }
        },
        "required": [
          "kind",
          "total_rows",
          "returned_limit",
          "offset",
          "page_size"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "command",
      "row_count",
      "row_count_returned",
      "truncated",
      "columns",
      "rows"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.