SQL Lab lets project editors query their Phoenix data directly in Apache Superset. Use it when the dashboard does not answer a question or when you need a custom table, aggregation, or export.

Before you start • You must be a project editor. View-only users cannot use SQL Lab. • The project dashboard must have been provisioned after SQL Lab access was enabled. If SQL Lab or the dataset is missing, ask a Phoenix administrator to reprovision the project resources. • Treat fields beginning with pi_ as potentially identifiable information. Do not copy or share them outside the approved project context.

Open SQL Lab

  1. Open your Phoenix project and go to Explore → Dashboard.
  2. In Superset, open SQL → SQL Lab.
  3. Select the Google BigQuery database.
  4. Select your project schema. Its name is project_id followed by the Phoenix project ID, for example project_id123.
  5. Write the query, select Run, inspect the results, and download them only when the project permits it.

Which dataset should I use? Use deduped_generalised_messages for most custom analysis. It contains the latest version of every distinct post or comment, deduplicated by platform, data_type, and phoenix_platform_message_id.

Use tabulated_messages when you need fields produced by Phoenix classification or the joined post-and-comment dashboard model. This table can contain repeated post values when a post has multiple comments or classifications, so use distinct IDs or the deduplicated dataset for message counts.

Safe query habits • Use SELECT statements and common table expressions only. • Start with a small LIMIT, normally 100 or 1,000 rows. • Filter by dates or platforms before selecting raw text. • Use COUNT(DISTINCT phoenix_platform_message_id) when counting messages in a joined dataset. • Check a small sample before downloading or sharing results. • Never include pi_ columns unless the research question requires them and their use is approved.

Example: count messages by platform and type SELECT platform, data_type, COUNT(*) AS message_count FROM project_id123.deduped_generalised_messages GROUP BY platform, data_type ORDER BY message_count DESC;

Replace project_id123 with your project schema.

Generate SQL with Claude Copy the prompt below into Claude, replace the bracketed values, and describe the question you want to answer.

CLAUDE PROMPT You are helping me write a read-only Apache Superset SQL Lab query using BigQuery Standard SQL.

Phoenix project schema: project_id[PROJECT_ID] Preferred table: deduped_generalised_messages

Available columns: gather_id, gather_batch_id, gathered_at, phoenix_processed_at, gather_type, platform, data_type, pi_platform_message_id, pi_platform_message_author_id, pi_platform_message_author_name, pi_platform_parent_message_id, pi_platform_root_message_id, pi_text, pi_platform_message_url, platform_message_last_updated_at, phoenix_platform_message_id, phoenix_platform_message_author_id, phoenix_platform_parent_message_id, phoenix_platform_root_message_id, like_count, share_count, comment_count, tiktok_post_plays, x_post_retweeted_id, x_is_quote, x_is_reply.

My research question: [DESCRIBE THE QUESTION, DATE RANGE, PLATFORMS, AND OUTPUT YOU NEED]

Requirements:

  1. Return exactly one SELECT query. Common table expressions are allowed.
  2. Use BigQuery Standard SQL and reference project_id[PROJECT_ID].deduped_generalised_messages.
  3. Use only the columns listed above. Do not invent tables or columns.
  4. Add appropriate date and platform filters.
  5. Add LIMIT 1000 unless the result is an aggregate with fewer rows.
  6. Do not use INSERT, UPDATE, DELETE, MERGE, CREATE, ALTER, DROP, TRUNCATE, or other data-changing statements.
  7. Avoid pi_ fields unless my question explicitly requires identifiable data. If it does, warn me before including them.
  8. After the SQL, give a short explanation of what each part does and state any assumptions.
  9. If essential details are missing, ask concise clarification questions instead of guessing. END PROMPT

Before running generated SQL Confirm the schema uses your project ID, every field exists in the selected dataset, the query is read-only, the date range is correct, and the row limit is reasonable. Claude can make mistakes; the person running the query remains responsible for checking the SQL and handling the resulting data safely.

Troubleshooting • SQL Lab is missing: confirm you are a project editor and ask an administrator to reprovision the project. • The schema or dataset is missing: confirm you selected the correct BigQuery database and project_id schema. • Access denied: do not switch to another project's schema; ask an administrator to check your project role. • Unexpectedly high counts: check whether you queried tabulated_messages and use distinct message IDs or deduped_generalised_messages instead.