Your First Query

1. Sign in

Go to opteryx.app and sign in with Google, Microsoft or GitHub. There's no card to enter, and the free quota covers everything on this page. See Logging In if you get stuck.

2. Run the example query

Opteryx Studio opens with this query already in the editor. It reads public.astronomy.moons, a sample table every signed-in user can read:

SELECT
    planet,
    COUNT(*) AS moons
FROM
    public.astronomy.moons
GROUP BY ALL
ORDER BY
    moons DESC

Press Run (⌘↵ / Ctrl+Enter). The results grid shows the first rows:

planet   moons
Saturn      16
Jupiter      9
Neptune      8
Uranus       5
...

3. See what it cost

The status bar under the results shows the row count, how long the query took and the bytes scanned. Bytes scanned is what Opteryx meters, so you can see what each query costs as you go. See Cost Model.

1. Query a public dataset

The datasets under public.geopolitics and public.security are open to anonymous reads over OData. This query lists the three largest European countries by area:

curl 'https://odata.opteryx.app/api/v4/public/geopolitics/countries?$select=country_name_common,capital,area_km2&$filter=region%20eq%20%27Europe%27&$orderby=area_km2%20desc&$top=3'

Keep the URL in single quotes. In double quotes, the shell would expand $top and $filter as variables.

{
  "@odata.context": "/api/v4/$metadata#public_geopolitics_countries",
  "value": [
    { "country_name_common": "Russia", "capital": "Moscow", "area_km2": 17098242.0 },
    { "country_name_common": "Ukraine", "capital": "Kyiv", "area_km2": 603500.0 },
    { "country_name_common": "France", "capital": "Paris", "area_km2": 551695.0 }
  ],
  "@odata.nextLink": "/api/v4/public/geopolitics/countries?%24select=...&%24skip=3"
}

The @odata.nextLink points to the next page of results.

2. See what else is open

The service root lists every dataset you can read. Without a token, that's the anonymous ones:

curl 'https://odata.opteryx.app/api/v4/'

The same URLs work in Power BI and Excel. Point either one at the service root and it loads the datasets with no driver to install.

1. Install

pip install opteryx-core

You need Python 3.11 or later. See Installing Opteryx Core for details.

2. Query the built-in sample data

$planets ships inside the engine, so this works with no files and no network:

import opteryx

session = opteryx.session()
for morsel in session.execute_to_morsels(
    "SELECT name, gravity FROM $planets ORDER BY gravity DESC LIMIT 3"
):
    for row in morsel:
        print(row.name, row.gravity)

Jupiter 23.1
Neptune 11.0
Earth 9.8

3. Query your own file

Point READ_PARQUET at any Parquet file on disk, by path. Nothing needs to be registered first:

for morsel in session.execute_to_morsels(
    "SELECT city, SUM(amount) AS total "
    "FROM READ_PARQUET('sales.parquet') "
    "GROUP BY city ORDER BY total DESC"
):
    for row in morsel:
        print(row.city, row.total)

READ_PARQUET also accepts glob patterns and https:// URLs. See READ_PARQUET, and Querying Local Data for registering folders as named datasets.