---
title: "spanner-list-tables"
type: docs
weight: 3
description: >
  A "spanner-list-tables" tool retrieves schema information about tables in a
  Google Cloud Spanner database.
---

## About

A `spanner-list-tables` tool retrieves comprehensive schema information about
tables in a Cloud Spanner database. It automatically adapts to the database
dialect (GoogleSQL or PostgreSQL) and returns detailed metadata including
columns, constraints, and indexes.

This tool is read-only and executes pre-defined SQL queries against the
`INFORMATION_SCHEMA` tables to gather metadata. The tool automatically detects
the database dialect from the source configuration and uses the appropriate SQL
syntax.

### Features

- **Automatic Dialect Detection**: Adapts queries based on whether the database
  uses GoogleSQL or PostgreSQL dialect
- **Comprehensive Schema Information**: Returns columns, data types, constraints,
  indexes, and table relationships
- **Flexible Filtering**: Can list all tables or filter by specific table names
- **Output Format Options**: Choose between simple (table names only) or detailed
  (full schema information) output

### Use Cases

1. **Database Documentation**: Generate comprehensive documentation of your
   database schema
2. **Schema Validation**: Verify that expected tables and columns exist
3. **Migration Planning**: Understand the current schema before making changes
4. **Development Tools**: Build tools that need to understand database structure
5. **Audit and Compliance**: Track schema changes and ensure compliance with
   data governance policies


## Compatible Sources

{{< compatible-sources >}}

## Parameters

The tool accepts two optional parameters:

| **parameter** | **type** | **default** | **description**                                                                                      |
|---------------|:--------:|:-----------:|------------------------------------------------------------------------------------------------------|
| table_names   |  string  |     ""      | Comma-separated list of table names to filter. If empty, lists all tables in user-accessible schemas |
| output_format |  string  | "detailed"  | Output format: "simple" returns only table names, "detailed" returns full schema information         |


## Example

### Basic Usage - List All Tables

```yaml
kind: source
name: my-spanner-db
type: spanner
project: ${SPANNER_PROJECT}
instance: ${SPANNER_INSTANCE}
database: ${SPANNER_DATABASE}
dialect: googlesql  # or postgresql
---
kind: tool
name: list_all_tables
type: spanner-list-tables
source: my-spanner-db
description: Lists all tables with their complete schema information
```

### List Specific Tables

```yaml
kind: tool
name: list_specific_tables
type: spanner-list-tables
source: my-spanner-db
description: |
  Lists schema information for specific tables.
  Example usage:
  {
    "table_names": "users,orders,products",
    "output_format": "detailed"
  }
```

## Output Format

### Simple Format

When `output_format` is set to "simple", the tool returns a minimal JSON structure:

```json
[
  {
    "schema_name": "public",
    "object_name": "users",
    "object_details": {
      "name": "users"
    }
  },
  {
    "schema_name": "public",
    "object_name": "orders",
    "object_details": {
      "name": "orders"
    }
  }
]
```

### Detailed Format

When `output_format` is set to "detailed" (default), the tool returns
comprehensive schema information:

```json
[
  {
    "schema_name": "public",
    "object_name": "users",
    "object_details": {
      "schema_name": "public",
      "object_name": "users",
      "object_type": "BASE TABLE",
      "columns": [
        {
          "column_name": "id",
          "data_type": "INT64",
          "ordinal_position": 1,
          "is_not_nullable": true,
          "column_default": null
        },
        {
          "column_name": "email",
          "data_type": "STRING(255)",
          "ordinal_position": 2,
          "is_not_nullable": true,
          "column_default": null
        }
      ],
      "constraints": [
        {
          "constraint_name": "PK_users",
          "constraint_type": "PRIMARY KEY",
          "constraint_definition": "PRIMARY KEY (id)",
          "constraint_columns": [
            "id"
          ],
          "foreign_key_referenced_table": null,
          "foreign_key_referenced_columns": []
        }
      ],
      "indexes": [
        {
          "index_name": "idx_users_email",
          "index_type": "INDEX",
          "is_unique": true,
          "is_null_filtered": false,
          "interleaved_in_table": null,
          "index_key_columns": [
            {
              "column_name": "email",
              "ordering": "ASC"
            }
          ],
          "storing_columns": []
        }
      ]
    }
  }
]
```

## Reference

| **field**    | **type** | **required** | **description**                                    |
|--------------|:--------:|:------------:|----------------------------------------------------|
| type         |  string  |     true     | Must be "spanner-list-tables"                      |
| source       |  string  |     true     | Name of the Spanner source to query                |
| description  |  string  |    false     | Description of the tool that is passed to the LLM  |
| authRequired | string[] |    false     | List of auth services required to invoke this tool |

## Advanced Usage

### Example with Agent Integration

```yaml
kind: source
name: spanner-db
type: spanner
project: my-project
instance: my-instance
database: my-database
dialect: googlesql
---
kind: tool
name: schema_inspector
type: spanner-list-tables
source: spanner-db
description: |
  Use this tool to inspect database schema information.
  You can:
  - List all tables by leaving table_names empty
  - Get specific table schemas by providing comma-separated table names
  - Choose between simple (names only) or detailed (full schema) output

  Examples:
  1. List all tables with details: {"output_format": "detailed"}
  2. Get specific tables: {"table_names": "users,orders", "output_format": "detailed"}
  3. Just get table names: {"output_format": "simple"}
```


## Additional Resources

- This tool is read-only and does not modify any data
- The tool automatically handles both GoogleSQL and PostgreSQL dialects
- Large databases with many tables may take longer to query
