Run your first SQL query

Define a product table, write a row and read it back through the HTTP API. Then try a grouped query and a SQL write. The examples are small enough to check the returned values by hand.

Before you startCopy Anchor Link

Open Connect on a running instance. Copy its complete HTTPS database address and credential. Keep any path in the address unchanged. These examples use Bash and cURL.

export OC_URL='<complete HTTPS database address from Connect>'
# Load OC_TOKEN from your environment or secret manager.
: "${OC_TOKEN:?Set OC_TOKEN before continuing}"

The five stepsCopy Anchor Link

1. Register a schemaCopy Anchor Link

A schema declares a table and its columns. Register it once; every surface reads the same declaration. Full reference in the schema reference.

curl -X POST "${OC_URL%/}/schemas" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @- <<'TOML'
namespace = "shop"
table = "products"
primary_key = ["id"]

[[columns]]
name = "id"
ty = "str"
required = true

[[columns]]
name = "name"
ty = "str"

[[columns]]
name = "price"
ty = "i64"
TOML

2. Insert a rowCopy Anchor Link

Save one product with a stable ID. Writing the same ID again can replace the row. Use SQL INSERT in step five when you need an insert operation.

curl -X POST "${OC_URL%/}/rows/shop.products" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"sku-8842","name":"Carbon Marathon","price":149}'

3. Select it backCopy Anchor Link

One endpoint, one JSON field. The response carries a kind so your code can switch on the statement type.

curl -X POST "${OC_URL%/}/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT id, name, price FROM shop.products WHERE price < 200"}'

4. Group and aggregateCopy Anchor Link

Aggregates, GROUP BY and HAVING run in the engine, not in your application.

SELECT name, COUNT(*) AS n, AVG(price) AS avg_price
FROM shop.products
GROUP BY name
HAVING COUNT(*) >= 1
ORDER BY avg_price DESC

5. Write with SQLCopy Anchor Link

Send this statement through the SQL endpoint from step three. It inserts a second product into the same table; confirm it with SELECT. For a two-table example, see explicit SQL joins.

INSERT INTO shop.products (id, name, price) VALUES ('sku-8843', 'Trail Runner', 129);

From a PostgreSQL clientCopy Anchor Link

Use the PostgreSQL connection details shown in Database login to read data with a supported client. The currently offered login is read-only: run the write examples above through HTTPS. Test the queries your client or ORM sends; PostgreSQL protocol support is not a promise of full PostgreSQL behavior. See connect a SQL client.

What to read nextCopy Anchor Link

• SQL reference — Every clause that works today, and the ones that do not, with the response shape per statement kind.

• Constraints — Primary keys, foreign keys and what the engine enforces on write.

• Materialized views — Precompute a query and keep it current.

• By industry — Worked models: orders, ledgers, inventory, events.