> This page is for version Latest (default).
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.coactive.ai/latest/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coactive.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coactive.ai/_mcp/server.

# Getting Started with the Query Engine

The Query Engine gives you a SQL interface to the tables Coactive creates for each dataset. Use it to filter and aggregate concept scores, dynamic tag scores, and the metadata ingested with your files. This page covers how to open the Query Engine, find the tables available to you, and read their columns.

For the columns in each table, see [SQL Table Reference](/docs-guides/core-features/query-engine/sql-table-reference). For dynamic tag views, see [Dynamic Tag Tables](/docs-guides/core-features/query-engine/dynamic-tag-tables).

## Open the Query Engine

1. In the Coactive app, open the **Queries** tab.
2. Select the dataset you want to query.

![Overview of the Coactive query engine](/_fern-files/_img/5ac910618e02cd0d74dab40c27e58b50441c3ba410957220c0358fac7301be95.webp)

## List available tables

Run `SHOW TABLES` to see the tables and views available in the selected dataset:

```sql
SHOW TABLES;
```

![SHOW TABLES results listing the dataset's coactive\_table tables, a concept table, and dt\_ dynamic tag views](/_fern-files/_img/e2ed227f39e5d8d041f26985dc86df7911fcb39ba2cad539d22671a11252348b.webp)

## Retrieve column names from a table

Run `DESCRIBE` to see a table's column names and data types:

```sql
DESCRIBE coactive_table;
```

For example, `coactive_table` returns columns such as `coactive_image_id`, `coactive_video_id`, `keyframe_index`, `path`, and `metadata`. Concept columns (`[concept_name]_prob` and `[concept_name]`) are in `coactive_table_adv`, not `coactive_table`.

## Read metadata values

The `metadata` column in `coactive_table` and `coactive_table_video` holds file-level metadata as a `map<string,string>`. Read a value by its key with `metadata['key']` or `element_at(metadata, 'key')`. JSON functions such as `get_json_object` don't work on this column.

Keys depend on the metadata ingested with your files. To list the keys on a row, run:

```sql
SELECT map_keys(metadata) FROM coactive_table_video LIMIT 1;
```

Then read the values you need. In this example, replace `series_name` with a key returned by `map_keys`:

```sql
SELECT
  coactive_video_id,
  path,
  metadata['series_name'] AS series_name
FROM coactive_table_video
LIMIT 10;
```

## Understand data volume

To measure the size of your dataset and estimate query performance, count the rows in a table. For larger queries, a Common Table Expression (CTE) can make the query easier to read:

```sql
WITH row_count AS (
  SELECT COUNT(*) AS total_rows
  FROM coactive_table
)
SELECT
  total_rows,
  CONCAT('This table contains ', total_rows, ' rows.') AS summary
FROM row_count;
```

* **WITH row_count AS**: Creates a temporary table that stores the total row count.
* **CONCAT**: Builds a readable summary of the data volume.

Expected output:

![Overview of the Coactive query engine](/_fern-files/_img/23b77685bd1c1c1fef83d92d935051629a63526d74a39ef046501feea113eca1.webp)

## Next steps

* To look up columns and types for each core and video structure table, see [SQL Table Reference](/docs-guides/core-features/query-engine/sql-table-reference).
* To check dataset size, ingestion, and ad segments, see [Query Your Dataset with SQL](/docs-guides/deep-dives/query-your-dataset-with-sql).
* For example queries on scores, see [Analyzing Concepts with SQL](/docs-guides/deep-dives/analyzing-concepts-with-sql) and [Analyzing Dynamic Tags with SQL](/docs-guides/deep-dives/analyzing-dynamic-tags-with-sql).
* To run queries through the API, see [Programmatically Retrieve SQL Results](/docs-guides/deep-dives/programmatically-retrieve-sql-results).