Getting started (5)

Last updated Oct 1, 2026 This guide will instruct you through:

  • Creating your first R2 bucket and enabling its data catalog.
  • Creating an API token needed for pipelines to authenticate with your data catalog.
  • Creating your first pipeline with a simple ecommerce schema that writes to an Apache Iceberg ↗︎ table managed by Basin Catalog.
  • Sending sample ecommerce data via HTTP endpoint.
  • Validating data in your bucket and querying it with Basin SQL.

Prerequisites

  1. Sign up for a Cloudflare account ↗︎.
  2. Install Node.js ↗︎.

<details>

<summary>

Node.js version manager

</summary>

Use <a href="https://viteplus.dev/guide/env">Vite+ (<code>vp env</code>) ↗︎</a> to install and manage Node.js versions.

For supported Node.js versions, refer to the <a href="https://developers.cloudflare.com/workers/wrangler/install-and-update/#install-wrangler">Wrangler system requirements</a>.

</details>

1. Create an R2 bucket

  1. If not already logged in, run:npmyarnpnpm

npx wrangler login

yarn wrangler login

pnpm wrangler login

  1. Create an R2 bucket:npmyarnpnpm

npx wrangler r2 bucket create pipelines-tutorial

yarn wrangler r2 bucket create pipelines-tutorial

pnpm wrangler r2 bucket create pipelines-tutorial

  1. In the Cloudflare dashboard, go to the R2 object storage page. Go to Overview ↗
  2. Select Create bucket.
  3. Enter the bucket name: pipelines-tutorial
  4. Select Create bucket.

2. Enable Basin Catalog

Enable the catalog on your R2 bucket:

npmyarnpnpm

npx wrangler basin catalog enable pipelines-tutorial

yarn wrangler basin catalog enable pipelines-tutorial

pnpm wrangler basin catalog enable pipelines-tutorial

When you run this command, take note of the "Warehouse" and "Catalog URI". You will need these later.

  1. In the Cloudflare dashboard, go to the R2 object storage page. Go to Overview ↗
  2. Select the bucket: pipelines-tutorial.
  3. Switch to the Settings tab, scroll down to Basin Catalog, and select Enable.
  4. Once enabled, note the Catalog URI and Warehouse name.

3. Create an API token

Basin Pipelines must authenticate to Basin Catalog with an R2 API token that has catalog and R2 permissions.

  1. In the Cloudflare dashboard, go to the R2 object storage page. Go to Overview ↗
  2. Select Manage API tokens.
  3. Select Create Account API token.
  4. Give your API token a name.
  5. Under Permissions, choose the Admin Read & Write permission.
  6. Select Create Account API Token.
  7. Note the Token value.

Note

This token also includes the Basin SQL Read permission, which allows you to query your data with Basin SQL.

4. Create a pipeline

First, create a schema file that defines your ecommerce data structure:

Create schema.json:

{
    "fields": [
        {
            "name": "user_id",
            "type": "string",
            "required": true
        },
        {
            "name": "event_type",
            "type": "string",
            "required": true
        },
        {
            "name": "product_id",
            "type": "string",
            "required": false
        },
        {
            "name": "amount",
            "type": "float64",
            "required": false
        }
    ]
}

Use the interactive setup to create a pipeline that writes to Basin Catalog:

npmyarnpnpm

npx wrangler basin pipelines setup

yarn wrangler basin pipelines setup

pnpm wrangler basin pipelines setup

Follow the prompts:

  1. Pipeline name: Enter ecommerce
  2. Stream configuration:
  3. Enable HTTP endpoint: yes
  4. Require authentication: no (for simplicity)
  5. Configure custom CORS origins: no
  6. Schema definition: Load from file
  7. Schema file path: schema.json (or your file path)
  8. Sink configuration:
  9. Destination type: Data Catalog Table
  10. R2 bucket name: pipelines-tutorial
  11. Namespace: default
  12. Table name: ecommerce
  13. Catalog API token: Enter your token from step 3
  14. Compression: zstd
  15. Roll file when size reaches (MB): 100
  16. Roll file when time reaches (seconds): 10 (for faster data visibility in this tutorial)
  17. SQL transformation: Choose Use simple ingestion query to use:

sql INSERT INTO ecommerce_sink SELECT * FROM ecommerce_stream

After setup completes, note the HTTP endpoint URL displayed in the final output.

  1. In the Cloudflare dashboard, go to Basin Pipelines > Pipelines. Go to Pipelines ↗
  2. Select Create Pipeline.
  3. Connect to a Stream:
  4. Pipeline name: ecommerce
  5. Enable HTTP endpoint for sending data: Enabled
  6. HTTP authentication: Disabled (default)
  7. Select Next
  8. Define Input Schema:
  9. Select JSON editor

  10. Copy in the schema:

    json { "fields": [ { "name": "user_id", "type": "string", "required": true }, { "name": "event_type", "type": "string", "required": true }, { "name": "product_id", "type": "string", "required": false }, { "name": "amount", "type": "f64", "required": false } ] }

  11. Select Next

  12. Define Sink:
  13. Select your R2 bucket: pipelines-tutorial
  14. Storage type: Basin Catalog
  15. Namespace: default
  16. Table name: ecommerce
  17. Advanced Settings: Change Maximum Time Interval to 10 seconds
  18. Select Next
  19. Credentials:
  20. Disable Automatically create an Account API token for your sink
  21. Enter Catalog Token from step 3
  22. Select Next
  23. Pipeline Definition:

  24. Leave the default SQL query:

    sql INSERT INTO ecommerce_sink SELECT * FROM ecommerce_stream;

  25. Select Create Pipeline

  26. After pipeline creation, note the Stream ID for the next step.

5. Send sample data

Send ecommerce events to your pipeline's HTTP endpoint:

curl -X POST https://{stream-id}.ingest.cloudflare.com \
  -H "Content-Type: application/json" \
  -d '[
    {
      "user_id": "user_12345",
      "event_type": "purchase",
      "product_id": "widget-001",
      "amount": 29.99
    },
    {
      "user_id": "user_67890",
      "event_type": "view_product",
      "product_id": "widget-002"
    },
    {
      "user_id": "user_12345",
      "event_type": "add_to_cart",
      "product_id": "widget-003",
      "amount": 15.50
    }
  ]'

Replace {stream-id} with your actual stream endpoint from the pipeline setup.

6. Validate data in your bucket

  1. In the Cloudflare dashboard, go to the R2 object storage page.
  2. Select your bucket: pipelines-tutorial.
  3. Confirm that your pipeline created Iceberg metadata and data files. If the files do not appear, wait a few minutes and try again.
  4. The data is organized in the Apache Iceberg format with metadata tracking table versions.

7. Query your data using Basin SQL

Set up your environment to use Basin SQL:

export WRANGLER_BASIN_SQL_AUTH_TOKEN=YOUR_API_TOKEN

Or create a .env file with:

WRANGLER_BASIN_SQL_AUTH_TOKEN=YOUR_API_TOKEN

Where YOUR_API_TOKEN is the token you created in step 3. For more information on setting environment variables, refer to Wrangler system environment variables.

Query your data:

npmyarnpnpm

npx wrangler basin sql query "YOUR_WAREHOUSE_NAME" "SELECT user_id, event_type, product_id, amount FROM default.ecommerce WHERE event_type = 'purchase' LIMIT 10"

yarn wrangler basin sql query "YOUR_WAREHOUSE_NAME" "SELECT user_id, event_type, product_id, amount FROM default.ecommerce WHERE event_type = 'purchase' LIMIT 10"

pnpm wrangler basin sql query "YOUR_WAREHOUSE_NAME" "SELECT user_id, event_type, product_id, amount FROM default.ecommerce WHERE event_type = 'purchase' LIMIT 10"

Replace YOUR_WAREHOUSE_NAME with the warehouse name from step 2.

You can also query this table with any engine that supports Apache Iceberg. To connect other engines to Basin Catalog, refer to Connect to Iceberg engines.

Learn more

Managing catalogs

Enable or disable Basin Catalog on your bucket, retrieve configuration details, and authenticate your Iceberg engine.

Try another example

Detailed tutorial for setting up a simple fraud detection data pipeline, and generate events for it in Python.

Basin Pipelines

Understand SQL transformations and pipeline configuration.

Was this helpful?

YesNo

On this page

Getting started (5) - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/basin-sql/get-started/#page","headline":"Getting started","description":"Create your first pipeline to ingest streaming data and write to Basin Catalog as an Apache Iceberg table.","url":"https://developers.cloudflare.com/basin-sql/get-started/","inLanguage":"en","image":"https://developers.cloudflare.com/basin-sql/get-started/og.png?v=8fe96c60f1f68a3b","dateModified":"2026-10-01","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Understand how to query data with Basin SQL title: Query data image: https://developers.cloudflare.com/basin-sql/query-data/og.png?v=babebcf967cb2a0a

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/basin-sql/llms.txt
Use this file to discover all available pages before exploring further.