How Orcabase works

Orcabase has four layers. Your data comes in at the top, gets a clear meaning in the middle, and comes out as answers wherever you work. Answers only ever read your data, and with a read-only login nothing in Orcabase can change it.

1. Your data

Data reaches Orcabase in one of three ways, and you can mix them:

• Connected live. Your app’s Postgres database or a BigQuery project stays where it is. Orcabase queries it when someone asks a question, so answers always reflect the data as it is now.
• Synced on a schedule. Google Sheets and MySQL are copied into a warehouse Orcabase hosts, every 15 minutes to once a day. Hundreds of other apps sync the same way through Fivetran. See Sync data.
• Uploaded. A CSV, Parquet or JSON file becomes a table in a few clicks. See Upload files.

2. The Data Warehouse

Everything you connect becomes a data source in your organization. A data source is one database: either one you already run, or one Orcabase hosts for you (a Postgres server, or a DuckDB warehouse built for analysis). Synced and uploaded data always lands in a hosted one.

Every other part of Orcabase works through data sources: Explore browses them, the SQL Editor queries them, and the agent reads them. A DuckDB warehouse can also attach a Postgres data source, so one query can join synced spreadsheets with your app’s live data.

3. The semantic layer

Raw tables don’t say what your numbers mean. Is revenue every order, or only paid ones, minus refunds? The semantic layer is where you write that down, once:

• A data model describes a table: what you can group by (dimensions, like order date or plan), what you can add up (measures, like order amount) and how it joins to other tables.
• A metric is a named business number built on a model, like Revenue or Conversion rate. When a person checks it and clicks Certify, it becomes the definition everyone uses.

When anyone asks for a metric, Orcabase writes the SQL for that data source’s database from the current definition. Fix a definition, and every chart that uses it is fixed on its next run. See How metrics work.

4. Where you use it

How a question becomes an answer

Here’s what happens when you ask the agent “How much revenue did we make last month?”

1. The agent checks your metrics. There’s a certified Revenue metric, so it uses that.
2. Orcabase turns “Revenue, last month” into SQL for the database behind the metric, from the current definition.
3. The query runs against your data source, capped at 5,000 rows and 30 seconds.
4. The AI model sees a short summary of the result (at most 30 rows). You see the full result, as a chart.
5. The answer leads with the number, and “How I got this” lists each step, including the SQL that ran.

With no metric that fits, the agent reads the table’s columns and a few sample rows, then writes the SQL itself, and tells you so. Certified metrics are what make answers repeatable.

What Orcabase stores, and where

Under the hood

For the technically curious:

• The app at app.orcabase.co talks to the Orcabase API at api.tini.so. So do AI assistants, through the MCP endpoint at api.tini.so/api/mcp.
• Three database engines are supported: PostgreSQL, Google BigQuery and DuckDB. Metric queries compile to each one’s own SQL.
• Hosted Postgres servers sit behind a gateway with a connection pooler, and every connection uses TLS. Orcabase reads them as a dedicated read-only user.
• The Data Agent calls AI models through OpenRouter or Vercel AI Gateway, using the same tools that AI assistants get over MCP.