Read the columns you need

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

Select customer IDs and email addresses. Selecting named columns keeps the response focused on the fields your application uses.

Before you run it: Use LIMIT when exploring a table to keep the response small.

A primary key is the value that identifies one row. Here it is id. A projection simply selects columns: SELECT id, email returns those two fields and leaves region out of the response.

Return only the customer fields you needSelecting fewer columns does not remove other stored fields.

Three customer rowsThe sample stores id, email and region.
Select id and emailRequest those two fields with a result limit.
Read the projected rowsThe response omits region while the table keeps it.

Follow the example

Register the customer schema below.
Load the three sample customers.
Run the SELECT request in one language tab.
Read the rows in the response.

Set up the table

namespace   = "shop"
table       = "customers"
primary_key = ["id"]

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

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

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

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

[[indexes]]
name    = "by_region"
columns = ["region"]

Load sample rows

Load three customers via the bulk-insert endpoint so the response below has something to return.

# One-time seed of three customers - skip if you've already loaded data.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/rows/shop.customers/_batch" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": "c_1", "email": "alice@example.com", "region": "IN", "tier": "gold" },
    { "id": "c_2", "email": "bob@example.com",   "region": "US", "tier": "silver" },
    { "id": "c_3", "email": "carol@example.com", "region": "DE", "tier": "gold" }
  ]'

Run the request

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, email FROM shop.customers LIMIT 5"
  }'

Check the result

The result has kind select. Each row contains the selected column names and values.

{
  "kind": "select",
  "rows": [
    { "id": "c_1", "email": "alice@example.com" },
    { "id": "c_2", "email": "bob@example.com" },
    { "id": "c_3", "email": "carol@example.com" }
  ]
}

Every /sql response carries a kind field. "select" means the engine ran the query and the rows are in rows; each row is a JSON object keyed by column name.

How the database handles this request

The database reads customer records, keeps only id and email, and stops after at most five rows. In a query plan those operations are named Scan, Project and Limit. Selecting fewer columns changes the response; it does not remove fields from the stored records.

Important limits and checks

Missing LIMIT. Without a LIMIT, the query returns every row. On large tables that's slow and expensive. Add LIMIT early, drop it only when you mean it.
Forgot to qualify the table. Tables are addressed as namespace.table - FROM shop.customers, not FROM customers.
Asking for an undeclared column. Selecting a column that doesn't exist in the schema returns 400 unknown_column.

Continue

Continue to find rows with an exact value.

Follow the exampleCopy Anchor Link

Set up the tableCopy Anchor Link

Load sample rowsCopy Anchor Link

Run the requestCopy Anchor Link

Check the resultCopy Anchor Link

Important limits and checksCopy Anchor Link

ContinueCopy Anchor Link