Queries

Write, manage, and share SQL queries against Flipside’s blockchain data

Flipspace provides direct SQL access to Flipside’s complete data catalog. Query any table, join across schemas, and export results — all with standard SQL. Queries are automatically saved as you work.

Creating Queries

Navigate to Queries and click New Query to open the editor.

1. Name your query

   Add a Query Name and optional Description to help identify the query later.

2. Write your SQL

   Enter your SQL in the editor. Try this example to get started:

   SELECT
     DATE_TRUNC('day', block_timestamp) AS date,
     COUNT(*) AS swap_count,
     SUM(amount_in_usd) AS volume_usd
   FROM ethereum.defi.ez_dex_swaps
   WHERE block_timestamp >= DATEADD(day, -7, CURRENT_DATE)
   GROUP BY 1
   ORDER BY 1
   
3. Run your query

   Click Run (or Cmd+Enter) to execute. Results appear below the editor with row count, duration, and a Download CSV option. Your query is saved automatically.

Queries created by chat are also automatically saved and appear in your Queries dashboard.

Query Assistant

Press Cmd+B to open the chat assistant directly in the query editor. The assistant has full context of your current query and can write new queries, modify existing ones, explain results, or help debug SQL errors.

Managing Queries

Navigate to Queries to see all your queries. Each query displays its name, last modified date, last run time, and author.

Click any query to open it in the editor. From there you can:

• Run the query to get fresh results
• Edit the SQL and it will save automatically
• Duplicate the query to create a copy
• Delete the query permanently

Using Queries in Automations

Saved queries can be added to automations as Query blocks, letting you build repeatable workflows that run on a schedule.

Learn more about Automations

Build automated workflows with your saved queries

Using Variables

Variables make your queries reusable by letting you change values without editing the SQL. Add variables in the Variables panel on the right side of the editor.

Variable Syntax

Syntax	Use	Example
{{variable}}	For values (strings, numbers, dates)	WHERE address = '{{wallet_address}}'
{{{variable}}}	For identifiers (table names, columns)	SELECT * FROM {{{table_name}}}

Example with Variables

SELECT
  DATE_TRUNC('day', block_timestamp) AS date,
  COUNT(*) AS tx_count,
  SUM(amount_usd) AS volume_usd
FROM ethereum.core.ez_token_transfers
WHERE from_address = '{{wallet_address}}'
  AND block_timestamp >= DATEADD(day, -{{days_back}}, CURRENT_DATE)
GROUP BY 1
ORDER BY 1

This query uses two variables:

• wallet_address — The wallet to analyze
• days_back — Number of days to look back

When you run the query, you’ll be prompted to enter values for each variable.

Autocomplete

The editor provides autocomplete suggestions as you type, including table names, column names, and SQL keywords.

• Tab or Enter to accept the highlighted suggestion
• Ctrl+N to move down in the suggestion list
• Ctrl+P to move up in the suggestion list
• Ctrl+Y to select the current suggestion

Keyboard Shortcuts

Shortcut	Action
Cmd+Enter	Run query
Cmd+B	Open / close chat assistant
Tab	Accept autocomplete suggestion
Ctrl+N	Next autocomplete suggestion
Ctrl+P	Previous autocomplete suggestion
Ctrl+Y	Select autocomplete suggestion

API Access

Click the API button in the top-right corner of any query to get ready-to-use code for executing the query programmatically.

The panel provides:

• cURL — A complete curl command to execute the query via the REST API
• Flipside CLI — The flipside query run command with the query ID pre-filled

Both include the query’s unique ID so you can integrate it directly into scripts, pipelines, or applications. See the API Reference for full documentation.

Writing Queries

Table References

Use the full table path: {network}.{schema}.{table}

-- Ethereum DEX swaps
SELECT * FROM ethereum.defi.ez_dex_swaps LIMIT 10

-- Solana NFT sales
SELECT * FROM solana.nft.ez_nft_sales LIMIT 10

-- Cross-chain address labels
SELECT * FROM crosschain.core.address_labels WHERE address = '0x...'

Recommended Tables

Start with ez_* (curated) tables for most analyses:

Network	Common Tables
Ethereum	ethereum.defi.ez_dex_swaps, ethereum.core.ez_token_transfers
Solana	solana.defi.ez_dex_swaps, solana.nft.ez_nft_sales
Arbitrum	arbitrum.defi.ez_dex_swaps, arbitrum.core.ez_native_transfers

Query Optimization

Filter by date

Always include date filters to limit scan size:

WHERE block_timestamp >= '2024-01-01'
  AND block_timestamp < '2024-04-01'

Use specific columns

Select only needed columns instead of SELECT *:

SELECT block_timestamp, origin_from_address, amount_usd
FROM ethereum.defi.ez_dex_swaps

Limit results

Add LIMIT during exploration:

SELECT * FROM ethereum.defi.ez_dex_swaps
WHERE platform = 'uniswap-v3'
LIMIT 1000

Use aggregated tables

For high-level metrics, use pre-aggregated tables:

-- Faster than aggregating fact tables
SELECT * FROM solana.stats.ez_core_metrics_hourly

Example Queries

DEX Volume by Protocol

SELECT
  platform,
  DATE_TRUNC('day', block_timestamp) AS date,
  COUNT(*) AS swap_count,
  SUM(amount_in_usd) AS volume_usd
FROM ethereum.defi.ez_dex_swaps
WHERE block_timestamp >= DATEADD(day, -30, CURRENT_DATE)
GROUP BY 1, 2
ORDER BY 2 DESC, 4 DESC

Top Token Holders

SELECT
  user_address,
  SUM(amount) AS total_balance
FROM ethereum.core.ez_token_transfers
WHERE contract_address = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' -- USDC
  AND block_timestamp >= DATEADD(day, -90, CURRENT_DATE)
GROUP BY 1
ORDER BY 2 DESC
LIMIT 100

Cross-Chain Bridge Activity

SELECT
  destination_chain,
  DATE_TRUNC('day', block_timestamp) AS date,
  COUNT(DISTINCT sender) AS unique_bridgers,
  SUM(amount_usd) AS volume_usd
FROM ethereum.defi.ez_bridge_activity
WHERE block_timestamp >= '2024-01-01'
GROUP BY 1, 2
ORDER BY 2, 4 DESC

Next Steps

Export Results

Download query results as CSV or JSON

Data Explorer

Browse available tables and schemas

Schema Documentation

Complete table references

Chat

Ask the assistant to write or modify queries