> Documentation index: https://docs.beetl.io/llms.txt

# Quickstart

> From an empty tenant to a query returning rows.

Source: https://docs.beetl.io/getting-started/quickstart/
Last updated: 2026-11-10

One path from a brand new tenant to a SQL result: upload a CSV, query it, and read the rows. It
takes about ten minutes, and you need nothing set up in advance.

## Where your data is stored

Your tenant comes with Beetl's hosted store, an object store that Beetl registers for you when
the tenant is created. It is the tenant's default store, so everything in this quickstart lands
there without any configuration.

You can also bring your own S3-compatible bucket. See
[Use your own object storage](#use-your-own-object-storage) at the end of this page.

    ## Sign in [#sign-in]

    Go to [app.beetl.io](https://app.beetl.io), press Sign In and log in with your Beetl account. You
    land on Home, the Data Landscape graph, which starts out empty.

    ## Upload a file [#upload-a-file]

    On Home, open the File sets card, create a File Set, and drop in one CSV. Beetl accepts `.csv`,
    `.parquet`, `.jsonl` and `.ndjson` files up to 5 GiB each. A set takes the format of its first
    file.

    A file processor appears on Home for the set and imports the file into a Bronze dataset on its own.
    Its name is what you will write in SQL, and the processor's **Dataset** link takes you to it.
    Deleting the set later keeps the dataset. See [File Sets](https://docs.beetl.io/sources/file-sets).

    ## Check the dataset [#check-the-dataset]

    The dataset shows up as a node on Home. Click it to open the details pane, which shows the schema,
    the storage location and the object store it was written to. The Data preview tab shows the first 30
    rows.

    ## Query it [#query-it]

    Click Query in the sidebar and write SQL against the dataset name from step 2. Column
    autocompletion uses the real schema, so start typing a column name and Beetl offers the rest.

    ```sql
    SELECT *
    FROM your_dataset_name
    LIMIT 100;
    ```

    Run it with the button in the editor footer or with Ctrl/Cmd+Enter. The editor uses the DataFusion
    engine with the PostgreSQL dialect, and you can cancel a long run from the same footer.

    You now have rows.

    ## Keep the result [#keep-the-result]

    Beetl saves every result with its own URL.

    Switch to Chart to plot it, click a cell to see the column's role and the expression behind it,
    download it as CSV, or reopen it later from Recent results in the page header.

    > **Results are kept for 7 days.**
> After 7 days a result no longer opens. To keep a number longer, download the CSV,
> or turn the query into a pipeline that writes a dataset (next section). The full detail is on
> [Query results](https://docs.beetl.io/concepts/query-results).

## Next: your first pipeline

A pipeline turns that query into something that runs repeatedly and writes a dataset. On Home,
right-click the canvas and choose New pipeline. Add your Bronze dataset as a source, paste the SQL
you just ran as the first stage, preview it, add a destination, then Save and Deploy.

The full tour is in [Pipelines](https://docs.beetl.io/pipelines). If you hit an error code along the way, the
[Troubleshooting](https://docs.beetl.io/troubleshooting) page covers the common ones.

## Use your own object storage

Beetl's hosted store is enough to get started, but you can register any S3-compatible bucket as well, for
example to keep data in your own account or region. Open the account menu, choose Settings, and on
Object storage choose Add object store. Enter a name, the bucket's base URL and its credentials.

Beetl checks the bucket before it saves anything: it writes a test object, reads it back and
deletes it. If that round trip fails, the store is not added. Adding, editing and removing stores
requires the TenantAdmin role.

A tenant can have several stores, and one of them is the default that new datasets are written
to. Once a bucket is registered, you can also bring in files that already sit in it without copying
them: right-click the canvas on Home and choose Register data set. See
[Registered datasets](https://docs.beetl.io/sources/registered-datasets).