bq_describe_table
Retrieve table schema, metadata, and statistics from BigQuery to validate queries and analyze data structure before execution.
Instructions
Get table schema, metadata, and statistics
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| table_id | Yes | The table ID | |
| dataset_id | Yes | The dataset ID | |
| project_id | No | GCP project ID (uses default if not provided) | |
| format_output | No | Whether to format schema as table string |
Implementation Reference
- Core handler implementation for bq_describe_table: validates input using DescribeTableRequest, fetches table from BigQuery, extracts schema/metadata/statistics/partitioning/clustering, and optionally formats schema as table.async def describe_table( table_id: str, dataset_id: str, project_id: str | None = None, format_output: bool = False, ) -> dict[str, Any]: """Return schema metadata for a single table.""" try: request = validate_request( DescribeTableRequest, { "table_id": table_id, "dataset_id": dataset_id, "project_id": project_id, "format_output": format_output, }, ) except MCPBigQueryError as exc: return {"error": format_error_response(exc)} try: return await _describe_table_impl(request) except MCPBigQueryError as exc: return {"error": format_error_response(exc)} except Exception as exc: # pragma: no cover - defensive guard logger.exception("Unexpected error while describing table") wrapped = MCPBigQueryError(str(exc), code="DESCRIBE_TABLE_ERROR") return {"error": format_error_response(wrapped)} async def _describe_table_impl(request: DescribeTableRequest) -> dict[str, Any]: client = get_bigquery_client(project_id=request.project_id) project = request.project_id or client.project try: table = client.get_table(f"{project}.{request.dataset_id}.{request.table_id}") except NotFound as exc: raise TableNotFoundError(request.table_id, request.dataset_id, project) from exc schema = [serialize_schema_field(field) for field in table.schema or []] result: dict[str, Any] = { "table_id": request.table_id, "dataset_id": request.dataset_id, "project": project, "table_type": table.table_type, "schema": schema, "description": table.description, "created": serialize_timestamp(table.created), "modified": serialize_timestamp(table.modified), "expires": serialize_timestamp(getattr(table, "expires", None)), "labels": table.labels or {}, "statistics": { "num_bytes": getattr(table, "num_bytes", None), "num_rows": getattr(table, "num_rows", None), "num_long_term_bytes": getattr(table, "num_long_term_bytes", None), }, "location": table.location, } partitioning = partitioning_details(table) if partitioning: result["partitioning"] = partitioning clustering = getattr(table, "clustering_fields", None) if clustering: result["clustering_fields"] = list(clustering) if request.format_output and schema: result["schema_formatted"] = format_schema_table(schema) return result
- src/mcp_bigquery/server.py:217-242 (registration)Registration of the bq_describe_table tool in the MCP server's list_tools() method, defining name, description, and input schema matching the DescribeTableRequest model.types.Tool( name="bq_describe_table", description=("Get table schema, metadata, and statistics"), inputSchema={ "type": "object", "properties": { "table_id": { "type": "string", "description": "The table ID", }, "dataset_id": { "type": "string", "description": "The dataset ID", }, "project_id": { "type": "string", "description": "GCP project ID (uses default if not provided)", }, "format_output": { "type": "boolean", "description": "Whether to format schema as table string", }, }, "required": ["table_id", "dataset_id"], }, ),
- Pydantic BaseModel defining the input validation schema for bq_describe_table parameters: required table_id and dataset_id, optional project_id and format_output.class DescribeTableRequest(BaseModel): """Request model for describing a table.""" table_id: str = Field(..., min_length=1, max_length=1024) dataset_id: str = Field(..., min_length=1, max_length=1024) project_id: str | None = Field(None, pattern=PROJECT_ID_PATTERN) format_output: bool = Field(False)
- src/mcp_bigquery/server.py:369-376 (handler)Dispatch handler in MCP server's call_tool method that extracts arguments and invokes the describe_table implementation for bq_describe_table.elif name == "bq_describe_table": result = await describe_table( table_id=arguments["table_id"], dataset_id=arguments["dataset_id"], project_id=arguments.get("project_id"), format_output=arguments.get("format_output", False), ) return [types.TextContent(type="text", text=json.dumps(result, indent=2))]