# Orcabase documentation > Orcabase is the AI-native data platform for founders: all your business data in one place, with an AI agent that understands it. These docs show you how to bring your data together, define what your numbers mean, and get answers you can trust. Source: https://tini.so/docs · The app: https://app.orcabase.co ## Start here - [Quickstart](https://tini.so/docs/quickstart.md): From your invite to a first answer, a certified metric and a shared dashboard. - [How Orcabase works](https://tini.so/docs/how-it-works.md): The architecture on one page: where your data lives and how it flows. - [Connect your data](https://tini.so/docs/data.md): The four ways in, and how to choose between them. - [Key concepts](https://tini.so/docs/concepts.md): Data sources, metrics, widgets and the rest, in plain words. ## Your first month, in four moves 1. **Connect**: Bring your data together, live or synced. 2. **Define**: Certify what revenue, churn and the rest mean. 3. **Ask**: Get answers, charts and how they were found. 4. **Share**: Pin the numbers that matter where everyone sees them. ## Explore the platform ### Connect your data Databases, spreadsheets, files and apps, in one place. - [Overview](https://tini.so/docs/data.md): The four ways to bring data into Orcabase: connect a database, sync apps and spreadsheets, upload files, or let Orcabase host it. How to choose. - [PostgreSQL](https://tini.so/docs/data/postgresql.md): Connect your app’s PostgreSQL database with a read-only user. Queries run live, your tables are never copied, and the password is encrypted. - [BigQuery](https://tini.so/docs/data/bigquery.md): Connect Google BigQuery with a service account: the two roles it needs, how to create the JSON key, and what queries cost in your project. - [Hosted by Orcabase](https://tini.so/docs/data/hosted.md): Postgres servers and DuckDB warehouses that Orcabase runs for you: nothing to install, no passwords to manage, and a home for synced data. - [Upload files](https://tini.so/docs/data/upload-files.md): Turn a CSV, TSV, Parquet or JSON file into a table in a few clicks: what each database accepts, the 200 MB limit, and updating uploads. - [Sync data](https://tini.so/docs/data/sync.md): Copy data from Google Sheets, MySQL and hundreds of apps into your warehouse on a schedule: how syncs run, their statuses, and who manages them. - [Google Sheets](https://tini.so/docs/data/google-sheets.md): Sync a Google Sheet into your warehouse: share it with Orcabase, paste the link, and every tab becomes a table that refreshes on a schedule. - [MySQL](https://tini.so/docs/data/mysql.md): Sync tables from MySQL, MariaDB or Aurora into your warehouse on a schedule with a read-only user: setup steps, limits and how it works. - [Fivetran connectors](https://tini.so/docs/data/fivetran.md): Bring in Salesforce, HubSpot, Stripe, Google Ads and hundreds more through Fivetran, with a monthly allowance and table-by-table control. ### Explore & query Browse tables, write SQL, and chart the results. - [Explore](https://tini.so/docs/explore.md): Browse every schema, table and column you’ve connected, preview real rows, profile columns, and start a query or data model from any table. - [SQL Editor](https://tini.so/docs/sql-editor.md): A scratchpad for running SQL against any data source, with autocomplete, run selection and formatting. Save what works as a query. - [Queries](https://tini.so/docs/queries.md): Save SQL as a query, add parameters with {{ name }}, and give it a chart. How results are kept, and how metric queries differ from SQL. - [Charts](https://tini.so/docs/charts.md): The 16 chart types, from Number and Line to Funnel and Heatmap, and how to set up their data, display and number format in Orcabase. - [Notebooks](https://tini.so/docs/notebooks.md): Write queries and build charts in one scrolling document, add notes between them, then pin the charts to any dashboard in Orcabase. ### Metrics Define your key numbers once, so every answer agrees. - [Overview](https://tini.so/docs/semantic-layer.md): Why Orcabase asks you to define each number once, and how data models, metrics and metric queries fit together to keep answers consistent. - [Data models](https://tini.so/docs/data-models.md): Describe a table once: the dimensions to group by, the measures to add up, and how it joins to others. Scaffold a model from any table. - [Metrics](https://tini.so/docs/metrics.md): Define revenue, churn and your other key numbers once, then certify them: simple, ratio and derived metrics, formats, lineage and history. - [Metric queries](https://tini.so/docs/metric-queries.md): Ask for metrics by name, trend them by day, week or month, split and filter them, and save charts that follow the metric definitions. ### Data Agent Ask in plain words; get the answer and how it was found. - [Ask the agent](https://tini.so/docs/agent.md): Ask about your business in plain words and get the answer, a chart and how it got there. What the Data Agent can build, and its guardrails. - [Set up the agent](https://tini.so/docs/agent/setup.md): Choose Orcabase AI or your own OpenRouter or Vercel AI Gateway key, pick the models your team can use, and set a step limit per question. - [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage.md): What the AI provider sees, what it never sees, and how tokens, costs and the Orcabase AI credit are counted for your organization. ### Dashboards The numbers that matter, on one page you can share. - [Dashboards](https://tini.so/docs/dashboards.md): Pin charts and notes onto a free-form grid your whole team sees: add widgets, arrange them, edit charts in place and keep numbers fresh. - [Share a dashboard](https://tini.so/docs/dashboards/sharing.md): Turn on a public link so anyone can view a dashboard, no account needed: what viewers see, what stays private, and how to stop sharing. ### Connect AI Your data and definitions inside Claude and ChatGPT. - [Overview](https://tini.so/docs/connect-ai.md): Use your Orcabase data from Claude and ChatGPT over MCP: what your assistant can do, what it can’t, and how it compares with the Data Agent. - [Set up your assistant](https://tini.so/docs/connect-ai/setup.md): Create an API token, then add Orcabase to Claude Code, Claude Desktop, claude.ai or ChatGPT as an MCP connector. Commands and settings included. - [Tools reference](https://tini.so/docs/connect-ai/tools.md): Every MCP tool your AI assistant gets from Orcabase, grouped by what it does, plus what’s deliberately left out: no edits, deletes or settings. ### Workspace Members, roles, tokens and settings. - [Members and roles](https://tini.so/docs/workspace/members.md): Invite teammates with a link, choose who’s an admin, and see what each role can do. Members sign in with Google, in one or more organizations. - [API tokens](https://tini.so/docs/workspace/api-tokens.md): Create, use and revoke the API tokens that let AI assistants reach your data. Each token belongs to one organization and is shown only once. - [Settings](https://tini.so/docs/workspace/settings.md): Rename your organization, change its URL, set your name, switch between organizations, pick light or dark mode, and sign out of Orcabase. ### Reference Security, limits, fixes and quick answers. - [Security](https://tini.so/docs/security.md): How Orcabase keeps your data safe: read-only logins, encrypted credentials, organizations kept apart, AI guardrails and limits on every query. - [Limits](https://tini.so/docs/limits.md): Every limit in one place: rows per query, query time, upload size, chart sampling, Data Agent steps, sync frequency and Fivetran allowances. - [Troubleshooting](https://tini.so/docs/troubleshooting.md): Fixes for the errors people run into most: signing in, connecting data sources, queries and dashboards, metrics, the agent, syncs and MCP. - [FAQ](https://tini.so/docs/faq.md): Short answers to common questions about Orcabase: what it is, connecting and exporting your data, the AI agent, sharing, teams and pricing. ## Popular tasks - [Connect your app’s Postgres database](https://tini.so/docs/data/postgresql.md) - [Sync a Google Sheet](https://tini.so/docs/data/google-sheets.md) - [Define and certify revenue](https://tini.so/docs/metrics.md) - [Ask the agent why a number moved](https://tini.so/docs/agent.md) - [Build a Monday dashboard](https://tini.so/docs/dashboards.md) - [Share a dashboard outside your team](https://tini.so/docs/dashboards/sharing.md) - [Use Orcabase from Claude or ChatGPT](https://tini.so/docs/connect-ai/setup.md) - [Invite your team](https://tini.so/docs/workspace/members.md) ## Using these docs with AI Every page is also available as Markdown: add `.md` to its URL (for example https://tini.so/docs/quickstart.md), or request the page with `Accept: text/markdown`. https://tini.so/llms.txt lists every page, and https://tini.so/llms-full.txt has all of them in one file. --- # Quickstart > Go from your invite to a first answer, a certified metric and a shared dashboard: sign in, connect data, ask the agent and invite your team. Source: https://tini.so/docs/quickstart This page takes you from your invite to a dashboard your team checks every Monday. Each step builds on the one before, and each links to a page with the details. ## Before you start - **An invite to an organization.** An organization is your company’s space in Orcabase. When your company joins, we set it up and send you an invite link. Joining a team that already uses Orcabase? Ask one of its admins to [invite you](https://tini.so/docs/workspace/members). - **A Google account** with the email address the invite was sent to. Orcabase signs you in with Google, so there’s no password to create. - **Somewhere your data lives:** your app’s Postgres database, a BigQuery project, a Google Sheet or a file. No database at all? Orcabase can [host one for you](https://tini.so/docs/data/hosted). ## 1. Sign in 1. **Open your invite link** It looks like `https://app.orcabase.co/invite/…`. Continue with Google, using the account the invite was sent to. 2. **Pick your organization** You land on the **Organizations** page. Pick yours to open its **Home** page, where a **Get started** checklist ticks itself off as you work through this page. ## 2. Connect your data 1. **Add a data source** On Home, click **Connect a data source**, or go to **Data Sources → New data source**. Pick what you’re connecting to and fill in the details: see [PostgreSQL](https://tini.so/docs/data/postgresql) or [BigQuery](https://tini.so/docs/data/bigquery) for exactly what goes in each field. 2. **Test it** Open the new data source and click **Test connection**. **Connected** means Orcabase can read your data. > **Tip: Use a read-only login** > > Orcabase only ever reads your data. Connect it with a database user that can only read, and it can’t change anything even by mistake. The [PostgreSQL page](https://tini.so/docs/data/postgresql#read-only-user) has the SQL to create one. Data in Google Sheets, MySQL or an app like Stripe? Use [Sync data](https://tini.so/docs/data/sync) instead: it copies the data into your warehouse and keeps it up to date. ## 3. Look around Open **Explore** in the sidebar and pick your data source. You’ll see its schemas (groups of tables), then its tables, then each table’s columns. **Preview Data** shows real rows, so you can see what’s in there. Click **Query this table** to start a query from any table, then press ⌘ ↵ (Ctrl Enter on Windows) to run it. See [Explore](https://tini.so/docs/explore). ## 4. Ask the agent The Data Agent answers questions about your data in plain words. An admin turns it on once, in **Settings → Agent** (see [Set up the agent](https://tini.so/docs/agent/setup)). Then open **Chat** in the header and try: - “What data do we have, and what does each table hold?” - “How much revenue did we make last month?” - “Why did revenue drop last week?” Every answer leads with what it found, then a chart you can change, then “How I got this”: each step it took, so you can check it. See [Data Agent](https://tini.so/docs/agent). ## 5. Define your first metric “Revenue” can mean three different things to three people. A **metric** pins it down once, and every chart, teammate and agent uses the same definition. 1. **Draft it** Ask the agent: “Model our orders table and draft a revenue metric.” It describes the table as a [data model](https://tini.so/docs/data-models), drafts the metric, and tests it. Prefer to click? In **Explore**, open the table and click **Create data model**, then go to **Metrics → New metric**. 2. **Check it and certify it** Open the metric on the **Metrics** page. Its **Explore** tab charts it over time: if the numbers match what you expect, click **Certify**. Certified metrics get a check mark, and the agent reaches for them first. > **Tip: Start with five** > > Revenue, new customers, active customers, churn and average order value cover most weekly questions. See [Metrics](https://tini.so/docs/metrics). ## 6. Build a dashboard 1. **Make the charts** Ask the agent: “Put revenue by week and new customers by week on a dashboard called Monday.” It saves each chart as a query and pins them for you. Or build it yourself: **Dashboards → New dashboard**, then **Widgets** to add any saved chart or a text note. 2. **Arrange it** Drag a widget by its handle to move it, and drag its corner to resize it. Changes save as you go. See [Dashboards](https://tini.so/docs/dashboards). 3. **Share it (optional)** Click **Share** and switch on **Public** for a read-only link anyone can open, no account needed. Good for advisors, partners and clients. See [Share a dashboard](https://tini.so/docs/dashboards/sharing). ## 7. Invite your team Go to **Settings → Members → Invite member**, enter a teammate’s email and pick a role. Orcabase gives you an invite link to send them: it doesn’t email anyone for you. See [Members and roles](https://tini.so/docs/workspace/members). ## What to read next - [How Orcabase works](https://tini.so/docs/how-it-works): The architecture, and where your data lives. - [How metrics work](https://tini.so/docs/semantic-layer): Data models, metrics and why definitions matter. - [Connect AI](https://tini.so/docs/connect-ai): Ask from Claude or ChatGPT instead. - [Security](https://tini.so/docs/security): What Orcabase can and can’t do with your data. --- Previous: [Introduction](https://tini.so/docs.md) · Next: [How Orcabase works](https://tini.so/docs/how-it-works.md) All docs: https://tini.so/llms.txt --- # How Orcabase works > The architecture of Orcabase on one page: where your data lives, how it flows from your databases to answers, and what each layer does. Source: https://tini.so/docs/how-it-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. How data moves through Orcabase, from where it lives to where you use it. 1. **Your data** (wherever it already lives): - Your app’s database: PostgreSQL - A warehouse you have: Google BigQuery - Spreadsheets and files: Google Sheets, CSV, Parquet, JSON - Other databases and apps: MySQL, and hundreds of apps via Fivetran ↓ Connected live, synced on a schedule, or uploaded 2. **Data Warehouse** (data sources in your organization): - Connected databases: Queried live, where they are. Tables aren’t copied. - Hosted by Orcabase: Postgres servers and DuckDB warehouses that hold synced and uploaded data. ↓ Described once, in plain words 3. **Semantic layer** (what your numbers mean): - Data models: Each table’s dimensions, measures and joins. - Metrics: Revenue, churn and the rest: defined once, certified by a person. ↓ Asked for by name, turned into SQL, run against your data 4. **Where you use it** (same data, same definitions, everywhere): - Data Agent: Questions in plain words - SQL and notebooks: For people who write SQL - Dashboards: And public share links - Claude and ChatGPT: Through MCP ## 1. Your data Data reaches Orcabase in one of three ways, and you can mix them: - **Connected live.** Your app’s [Postgres database](https://tini.so/docs/data/postgresql) or a [BigQuery project](https://tini.so/docs/data/bigquery) 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](https://tini.so/docs/data/fivetran). See [Sync data](https://tini.so/docs/data/sync). - **Uploaded.** A CSV, Parquet or JSON file becomes a table in a few clicks. See [Upload files](https://tini.so/docs/data/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](https://tini.so/docs/data/hosted) (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](https://tini.so/docs/explore) browses them, the [SQL Editor](https://tini.so/docs/sql-editor) queries them, and the agent reads them. A DuckDB warehouse can also [attach](https://tini.so/docs/data/hosted#attach-postgres) 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](https://tini.so/docs/data-models) 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](https://tini.so/docs/metrics) 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](https://tini.so/docs/semantic-layer). ## 4. Where you use it | Surface | Who it’s for | What it does | | --- | --- | --- | | [Data Agent](https://tini.so/docs/agent) | Everyone | Answers questions in plain words, with a chart and its steps. Builds charts, dashboards and draft metrics when asked. | | [SQL Editor, queries, notebooks](https://tini.so/docs/sql-editor) | People who write SQL | Run SQL against any data source, save it, chart it. | | [Dashboards](https://tini.so/docs/dashboards) | The whole team, and people outside it | The numbers that matter on one page. Shareable with a public link. | | [Claude and ChatGPT](https://tini.so/docs/connect-ai) | People who already work in an AI assistant | The same tools as the agent, through MCP, from the assistant you already use. | ## 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 | What | Where it’s kept | | --- | --- | | Tables in a database you connect | In your database. Orcabase reads them when a query runs and doesn’t copy them. | | Synced and uploaded data | In a Postgres server or DuckDB warehouse that Orcabase hosts for your organization. | | The latest result of each saved query | In Orcabase, so dashboards open instantly. Only the latest run is kept, up to 5,000 rows. | | Queries, dashboards, notebooks, data models and metrics | In Orcabase, in your organization. | | Agent chats | In Orcabase, visible only to the person who started them. | | Database passwords, service account keys and AI keys | Encrypted in Orcabase. After you save one, it’s never shown again. | > **Note** > > Everything belongs to exactly one organization, and members only ever see their own organization’s data. See [Security](https://tini.so/docs/security) for the details. ## 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](https://tini.so/docs/connect-ai/tools). --- Previous: [Quickstart](https://tini.so/docs/quickstart.md) · Next: [Key concepts](https://tini.so/docs/concepts.md) All docs: https://tini.so/llms.txt --- # Key concepts > The words you’ll see in Orcabase, from data sources and schemas to metrics, widgets and API tokens, each explained in plain words. Source: https://tini.so/docs/concepts Most of Orcabase is built from a handful of ideas. Here’s each one, in the order you’ll meet them. The names in bold are what you’ll see in the app. ## Your workspace | Term | What it means | | --- | --- | | Organization | Your company’s space in Orcabase. Data sources, queries, dashboards and metrics all belong to one organization, and nobody outside it can see them. You can belong to more than one and switch between them. | | Member | A person in an organization. Members sign in with Google and have one of two roles: **Member** or **Admin**. See [Members and roles](https://tini.so/docs/workspace/members). | | Admin | A member who can also change the organization’s name and URL, set up the agent, and manage synced sources and hosted servers. | | Invite link | How someone joins an organization. An admin or member creates it and sends it; Orcabase doesn’t send email. | ## Data | Term | What it means | | --- | --- | | Data source | One database Orcabase can query: PostgreSQL, Google BigQuery or DuckDB. See [Connect your data](https://tini.so/docs/data). | | Hosted by Orcabase | A database Orcabase runs for you: a Postgres server or a DuckDB warehouse. You connect it the same way as a database you run yourself, with its address and login (or, for DuckDB, its URL and token). | | Warehouse | A database built for analysis. In Orcabase, usually a hosted DuckDB warehouse that synced and uploaded data lands in. | | Schema | A group of tables inside a database, like a folder. BigQuery calls these datasets. | | Table and column | A table holds rows, like a spreadsheet tab. Columns are its fields: order date, amount, plan. | | Sync | A copy of data from somewhere Orcabase can’t query directly (Google Sheets, MySQL, apps via Fivetran), refreshed on a schedule. See [Sync data](https://tini.so/docs/data/sync). | ## Analysis | Term | What it means | | --- | --- | | Query | A saved question for one data source: either SQL, or a **metric query** that asks for metrics by name. See [Queries](https://tini.so/docs/queries). | | Result | What a query returns: columns and rows, up to 5,000. Orcabase keeps the latest result of each saved query, which is what dashboards show. | | Parameter | A blank in a query, written `{{ name }}`, that you fill in before running it, like a date or a country. | | Chart | How a query’s result is drawn. Each query has at most one chart, in one of 16 types. See [Charts](https://tini.so/docs/charts). | | Notebook | A scrolling document of SQL cells, charts and notes, for working through an analysis in one place. | | Dashboard | A page of widgets on a free-form grid. What your team looks at every week. | | Widget | One tile on a dashboard: a query’s chart, or a text note. | | Share link | A dashboard’s public, read-only link. Anyone with it can view the dashboard without an account. | ## Metrics and the semantic layer | Term | What it means | | --- | --- | | Semantic layer | The place where you write down what your data means, so every chart and every AI answer uses the same definitions. In Orcabase it’s made of data models and metrics. See [How metrics work](https://tini.so/docs/semantic-layer). | | Data model | A description of one table (or one SQL statement): its dimensions, measures and joins. | | Dimension | Something you group or filter by: order date, plan, country. | | Measure | Something you add up or count: order amount, number of orders, number of buyers. | | Join | How two data models connect, like each order belonging to one customer. | | Metric | A named business number built from a measure, like Revenue, Average order value or Net revenue. | | Certified | A metric a person has checked and vouched for. Certified metrics show a check mark, and the agent prefers them. | | Draft and deprecated | A draft metric isn’t vouched for yet. A deprecated one still works, but is marked as on its way out. | | Time grain | The step a time series moves in: day, week, month, quarter or year. | ## AI | Term | What it means | | --- | --- | | Data Agent | Orcabase’s built-in AI analyst. It reads your data with the same tools you have, and can create charts, dashboards and draft metrics, but never edit or delete. See [Data Agent](https://tini.so/docs/agent). | | Chat | A conversation with the agent. Chats are saved, private to you, and keep answering if you leave the page. | | Model | The AI model that writes an answer, like Claude or GPT. Admins choose which ones your organization can use. | | Orcabase AI or your own key | The two ways to run the agent: on Orcabase’s AI account with a credit for your organization, or on your own OpenRouter or Vercel AI Gateway key. See [Set up the agent](https://tini.so/docs/agent/setup). | | MCP | Model Context Protocol, a standard way for AI assistants like Claude and ChatGPT to use outside tools. Orcabase speaks it, so your assistant can query your data. See [Connect AI](https://tini.so/docs/connect-ai). | | API token | A secret that lets an AI assistant or script reach one organization’s data. You can revoke it anytime. | --- Previous: [How Orcabase works](https://tini.so/docs/how-it-works.md) · Next: [Connect your data](https://tini.so/docs/data.md) All docs: https://tini.so/llms.txt --- # Connect your data > The four ways to bring data into Orcabase: connect a database, sync apps and spreadsheets, upload files, or let Orcabase host it. How to choose. Source: https://tini.so/docs/data Orcabase works with the data you already have. There are four ways to bring it in, and most companies use two or three of them side by side. ## The four ways in | Way in | Good for | Where the data lives | How fresh | | --- | --- | --- | --- | | [Connect a database](https://tini.so/docs/data/postgresql) | Your app’s Postgres database, a BigQuery project | Stays where it is | Live: every question reads it as it is now | | [Sync data](https://tini.so/docs/data/sync) | Google Sheets, MySQL, and hundreds of apps through Fivetran | Copied into a warehouse Orcabase hosts | On a schedule you pick | | [Upload a file](https://tini.so/docs/data/upload-files) | One-off exports: CSV, TSV, Parquet, JSON | A new table in a database of yours | A snapshot; upload again to refresh | | [Let Orcabase host it](https://tini.so/docs/data/hosted) | Teams without a database of their own | A Postgres server or DuckDB warehouse run by Orcabase | Whatever you sync or load into it | ## Which one should I use? - **Your app has a Postgres database:** [connect it](https://tini.so/docs/data/postgresql) with a read-only user. Answers are always live, and there’s nothing to keep in sync. - **You already use BigQuery:** [connect it](https://tini.so/docs/data/bigquery) with a service account. - **Your numbers live in spreadsheets:** [sync them](https://tini.so/docs/data/google-sheets). Each tab becomes a table. - **Your data is in an app** like Stripe, HubSpot or Google Ads: sync it [through Fivetran](https://tini.so/docs/data/fivetran). - **You have a one-off export:** [upload it](https://tini.so/docs/data/upload-files). > **Tip: Mixing sources** > > Synced and uploaded data can sit in the same DuckDB warehouse, and that warehouse can [attach your Postgres database](https://tini.so/docs/data/hosted#attach-postgres). Then one query can join your app’s live data with last night’s spreadsheet sync. ## Add a data source A connected database or a hosted one becomes a data source. To add one: 1. **Open the form** Go to **Data Sources → New data source**. 2. **Pick what you’re connecting to** - **PostgreSQL**: any Postgres database, whether Orcabase hosts it or you run it yourself. - **DuckDB**: a DuckDB warehouse, by its URL and token. We add yours for you when we set the warehouse up. - **Google BigQuery**: a BigQuery project. 3. **Fill it in and create it** Give it a name your team will recognize, like “App database”, fill in the details, and click **Create data source**. 4. **Test it** Open it and click **Test connection**. Orcabase runs a one-line query (`SELECT 1`), and **Connected** means everything works. Syncs are set up on a separate page, **Sync data**, because they copy data rather than connect to it. See [Sync data](https://tini.so/docs/data/sync). ## Manage data sources - **Data Sources** lists every source with its database type (for example `postgres`), where it points, and a **Test** button. - **Edit** changes the name and connection details. Leave a password or key blank to keep the one already saved. A data source’s type can’t change; create a new one instead. - **Explore** opens its schemas and tables. See [Explore](https://tini.so/docs/explore). - **Remove** deletes it from Orcabase after you confirm. Queries that use it stop working. The database itself isn’t touched. ## Where synced and uploaded data goes | Data | Lands in | | --- | --- | | Google Sheets and MySQL syncs | A DuckDB warehouse you pick, one schema per source | | Fivetran syncs | A hosted Postgres server, one schema per source | | Uploaded files | The DuckDB or Postgres data source you upload into | ## Connectors For popular apps, and what you can ask about each once it’s connected, see the [data sources catalog](https://tini.so/data-sources). - [PostgreSQL](https://tini.so/docs/data/postgresql): Your app’s database, queried live. - [BigQuery](https://tini.so/docs/data/bigquery): A Google Cloud project, through a service account. - [Google Sheets](https://tini.so/docs/data/google-sheets): Every tab becomes a table, synced on a schedule. - [MySQL](https://tini.so/docs/data/mysql): Tables copied into your warehouse on a schedule. - [Fivetran connectors](https://tini.so/docs/data/fivetran): Hundreds of apps and databases. - [Upload files](https://tini.so/docs/data/upload-files): CSV, TSV, Parquet and JSON. --- Previous: [Key concepts](https://tini.so/docs/concepts.md) · Next: [PostgreSQL](https://tini.so/docs/data/postgresql.md) All docs: https://tini.so/llms.txt --- # PostgreSQL > Connect your app’s PostgreSQL database with a read-only user. Queries run live, your tables are never copied, and the password is encrypted. Source: https://tini.so/docs/data/postgresql Connect the Postgres database behind your app, or any other PostgreSQL database. Orcabase queries it live, as a user you create for it, so every answer reflects your data as it is right now. Your tables stay where they are. ## Before you start - The database’s **host**, **port** (usually `5432`) and **database name**. - A **user and password** for Orcabase. We recommend creating a read-only user just for Orcabase (below). - The database has to **accept connections from the internet**. If it only allows known IP addresses, [message us](https://linkedin.com/company/tinilab) for the address to allow. Any PostgreSQL database you can reach over the internet works, whether you run it yourself or use a managed service. If Orcabase hosts your Postgres server, see [Hosted by Orcabase](https://tini.so/docs/data/hosted) instead: there’s nothing to set up. ## Create a read-only user Orcabase never needs to change your data. If it connects as a user that can only read, nothing in Orcabase can change it, even by mistake. Run this as an admin user on your database, with your own password: ```sql CREATE ROLE orcabase_readonly WITH LOGIN PASSWORD 'choose-a-long-random-password'; GRANT pg_read_all_data TO orcabase_readonly; ``` `pg_read_all_data` lets the user read every table, including ones you add later, and nothing else. On older Postgres versions, or to share only some schemas, grant access schema by schema instead: ```sql CREATE ROLE orcabase_readonly WITH LOGIN PASSWORD 'choose-a-long-random-password'; GRANT CONNECT ON DATABASE your_database TO orcabase_readonly; GRANT USAGE ON SCHEMA public TO orcabase_readonly; GRANT SELECT ON ALL TABLES IN SCHEMA public TO orcabase_readonly; -- Tables your app creates later are readable too: ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO orcabase_readonly; ``` Run the last line as the user that creates your app’s tables, since it applies to tables that user makes. Repeat the `USAGE`, `SELECT` and `DEFAULT PRIVILEGES` lines for each schema you want Orcabase to see. > **Tip: A time limit on the database’s side** > > Orcabase stops waiting for a query after 30 seconds. To make sure your database stops working on it too, give the user its own limit: > > ```sql > ALTER ROLE orcabase_readonly SET statement_timeout = '30s'; > ``` ## Connect it 1. **Start a new data source** Go to **Data Sources → New data source** and pick **PostgreSQL**. 2. **Fill in the details** | Field | What to enter | | --- | --- | | Name | What your team sees, like “App database”. | | Host | The server’s address, like `db.example.com`. | | Port | `5432` unless your provider says otherwise. | | Database | The database name, not the server name. | | Username | The user you created, like `orcabase_readonly`. | | Password | That user’s password. It’s encrypted and never shown again. | 3. **Create it and test it** Click **Create data source**, open it, and click **Test connection**. You should see **Connected**. ## How Orcabase uses the connection - **Live queries.** Explore, the SQL Editor, dashboards and the agent all query the database directly. The latest result of each saved query is kept so dashboards open instantly; your tables aren’t copied. - **Encrypted in transit.** Orcabase uses an encrypted (TLS) connection whenever your server offers one. - **Limits.** Each query returns at most 5,000 rows and stops after 30 seconds. See [Limits](https://tini.so/docs/limits). - **Safe parameters.** Values you type into a query’s [parameters](https://tini.so/docs/queries#parameters) are sent separately from the SQL, never pasted into it. - **Your password is write-only.** It’s encrypted when you save it and never sent back to the browser. When you edit the data source, leave the password blank to keep it. ## If the test fails | The error mentions | What to check | | --- | --- | | timeout, connection refused, no route to host | The host and port, and that the database accepts connections from the internet (firewall, security group or IP allowlist). | | password authentication failed | The username and password. Passwords are case-sensitive. | | database “…” does not exist | The database name. It’s the database inside the server, often not the same as the server’s name. | | no pg_hba.conf entry | Your server doesn’t allow this user to connect from outside. Allow it in your provider’s settings or pg_hba.conf. | | permission denied for table | The user can’t read that table. Grant it SELECT, or use pg_read_all_data (above). | More fixes are on [Troubleshooting](https://tini.so/docs/troubleshooting). --- Previous: [Connect your data](https://tini.so/docs/data.md) · Next: [BigQuery](https://tini.so/docs/data/bigquery.md) All docs: https://tini.so/llms.txt --- # BigQuery > Connect Google BigQuery with a service account: the two roles it needs, how to create the JSON key, and what queries cost in your project. Source: https://tini.so/docs/data/bigquery Connect a Google BigQuery project to query its datasets from Orcabase. Orcabase signs in as a service account you create, and queries run in your Google Cloud project, so BigQuery bills them there. ## Before you start - A Google Cloud project with BigQuery turned on. - Permission to create service accounts and keys in that project (IAM admin, or a project owner). ## Create a service account A service account is a login for software rather than a person. In the Google Cloud console: 1. **Create the account** Go to **IAM & Admin → Service Accounts → Create service account**. Name it something you’ll recognize, like `Orcabase`. 2. **Give it two roles** On the project, grant it: - **BigQuery Data Viewer**, to read tables. - **BigQuery Job User**, to run queries. With just these two, the account can read and query, but can’t change or delete anything. 3. **Download a JSON key** Open the service account, then **Keys → Add key → Create new key → JSON**. A `.json` file downloads. You’ll paste its contents into Orcabase in a moment. > **Tip: Share only some datasets** > > To limit what Orcabase can see, grant **BigQuery Data Viewer** on individual datasets instead of the whole project. **BigQuery Job User** still goes on the project, since that’s where queries run. ## Connect it 1. **Start a new data source** Go to **Data Sources → New data source** and pick **Google BigQuery**. 2. **Fill in the details** | Field | What to enter | | --- | --- | | Name | What your team sees, like “Analytics warehouse”. | | GCP project ID | The project that runs and pays for the queries, like `acme-analytics`. It’s the ID, not the display name. | | Service account JSON key | The whole contents of the key file, starting with `{` and ending with `}`. | 3. **Create it and test it** Click **Create data source**, open it, and click **Test connection**. Then delete the downloaded key file: Orcabase has an encrypted copy and never shows it again. ## Working with BigQuery in Orcabase - **Datasets show up as schemas** in [Explore](https://tini.so/docs/explore). Each dataset’s tables load when you open it, so large projects stay quick to browse. - **Write BigQuery SQL.** Queries run as BigQuery Standard SQL. Refer to tables as `dataset.table`, in backticks if the name needs them: ```sql SELECT DATE_TRUNC(DATE(created_at), MONTH) AS month, SUM(amount) AS revenue FROM `shop.orders` WHERE status = 'paid' GROUP BY month ORDER BY month ``` - **Parameters** like `{{ country }}` are sent to BigQuery as named query parameters, so values are never pasted into the SQL. See [Parameters](https://tini.so/docs/queries#parameters). - **Limits.** Each query returns at most 5,000 rows to Orcabase and stops after 30 seconds. ## What it costs BigQuery bills queries to the project you entered, at Google’s prices, usually by how much data a query reads. Orcabase doesn’t add anything on top. To keep costs down on big tables, filter by date (or by partition) in your SQL, and select only the columns you need. Returning 5,000 rows doesn’t mean BigQuery only read 5,000 rows. ## If the test fails | The error mentions | What to check | | --- | --- | | Access Denied, bigquery.jobs.create | The service account needs BigQuery Job User on the project you entered. | | Access Denied on a table or dataset | The service account needs BigQuery Data Viewer on that dataset or project. | | Not found: Project | The GCP project ID. Use the ID, not the display name. | | invalid character, or invalid JSON | Paste the whole key file, including the outer braces. | --- Previous: [PostgreSQL](https://tini.so/docs/data/postgresql.md) · Next: [Orcabase-hosted databases](https://tini.so/docs/data/hosted.md) All docs: https://tini.so/llms.txt --- # Orcabase-hosted databases > Postgres servers and DuckDB warehouses that Orcabase runs for you: nothing to install, no passwords to manage, and a home for synced data. Source: https://tini.so/docs/data/hosted No database of your own, or want a home for synced spreadsheets and uploaded files? Orcabase can host one for you. There are two kinds, and you can have both. ## Postgres servers and DuckDB warehouses | | Postgres server | DuckDB warehouse | | --- | --- | --- | | What it is | A regular PostgreSQL database | An analytics database, fast on large tables | | In the app | PostgreSQL | DuckDB | | Best for | Data your own tools also read and write, and Fivetran syncs | Synced spreadsheets and databases, uploaded files, joining sources | | Upload files | CSV and TSV (every column comes in as text) | CSV, TSV, Parquet and JSON (column types detected) | | Sync destination | Fivetran connectors | Google Sheets and MySQL | | Credentials | A Postgres user and password (admins create users on the server’s page) | The warehouse’s URL and token | Hosted databases are set up for your organization by the Orcabase team, as part of the data hosting add-on (see [Pricing](https://tini.so/pricing)). To add one, [message us](https://linkedin.com/company/tinilab). ## Connect a hosted Postgres server 1. **Start a new data source** Go to **Data Sources → New data source** and pick **PostgreSQL**. A hosted server is connected like any other Postgres database. 2. **Fill in the server** Admins can pick one of your organization’s servers under **Fill from a platform server**, which fills in its host and port. Otherwise copy them from the server’s connection string. **Database** is usually `postgres`, the one every server comes with. 3. **Add a user and create it** Enter a Postgres user and its password, then click **Create data source**. A user that can only read is the safest choice: create one on the server’s **Users** tab (see below) and give it access to the database. > **Note** > > Hosted data sources added before this change connected as a built-in user with no password. They keep working; the first time you edit one, it asks for a user and password. ## Postgres management in admincp (Platform admins) Platform admins manage hosted Postgres in **admincp → Projects**. Open a project to view its resources, live usage, password and connection strings, manage backups, start or stop it, and assign it to an organization. In dash, use **Data Sources** to connect and **Explore** to work with your data. Use the connection strings to point your own app or tools at the server. There are two: **Gateway — pooled** shares connections, which suits web apps that open many short ones. **Gateway — direct** is a plain connection, for long sessions, migrations and bulk loads. ## Your hosted DuckDB warehouse When the Orcabase team sets up a DuckDB warehouse for you, we add it to your **Data Sources** too, as a **DuckDB** source, ready to use. To add it again yourself, pick **DuckDB** and enter the warehouse’s query URL and token. A DuckDB warehouse is where built-in syncs land, and the best place for uploaded files. In Explore you can: - **New schema**: make a schema, a folder for tables, before loading data into it. - **Load data**: turn a file into a table. See [Upload files](https://tini.so/docs/data/upload-files). - **Profile**: on any table, see each column’s type, minimum, maximum, approximate number of unique values, average, spread and share of empty values. > **Note** > > SQL you run against a DuckDB warehouse can create and change tables in it, so you can build tables of your own there. Synced tables are rebuilt on every sync, so keep your own tables in a schema of their own. ## Attach a Postgres database to a DuckDB warehouse A DuckDB warehouse can reach into any Postgres data source in your organization and query it in place. Nothing is copied: the connection is made fresh for each query, and it’s read-only. That lets one query join synced data with your app’s live data. 1. **Open the warehouse in Explore** Go to **Explore**, select the DuckDB data source, and open its **Attachments** tab. 2. **Attach** Enter an **Alias** (a short name like `app`), pick the **Postgres data source**, and click **Attach**. 3. **Query across both** Refer to the Postgres tables as `alias.schema.table`: ```sql SELECT s.plan, COUNT(*) AS customers FROM app.public.customers AS c JOIN sheets.subscriptions AS s ON s.email = c.email GROUP BY s.plan ``` --- Previous: [BigQuery](https://tini.so/docs/data/bigquery.md) · Next: [Upload files](https://tini.so/docs/data/upload-files.md) All docs: https://tini.so/llms.txt --- # Upload files > Turn a CSV, TSV, Parquet or JSON file into a table in a few clicks: what each database accepts, the 200 MB limit, and updating uploads. Source: https://tini.so/docs/data/upload-files Got an export from your payment tool, your store or an ad platform? Upload it, and it becomes a table you can query, chart and ask the agent about, next to the rest of your data. ## What you can upload | Into | File types | Column types | | --- | --- | --- | | A DuckDB warehouse (recommended) | CSV, TSV, Parquet, JSON (.json, .ndjson, .jsonl) | Detected from the data: numbers, dates, true/false and text | | A Postgres data source | CSV and TSV | Every column comes in as text | Files can be up to 200 MB. The first row of a CSV or TSV file is used as the column names. ## Upload a file 1. **Pick where it goes** Open **Explore** and select the data source to upload into: usually your DuckDB warehouse. 2. **Choose the file** Click **Load data** and choose the file. Orcabase suggests a table name from the file name: `Stripe-Payments.csv` becomes `stripe_payments`. 3. **Pick a schema and a table name** **Schema** is the folder the table goes in (`main` in DuckDB, `public` in Postgres, unless you pick another). **Table name** can use letters, numbers and underscores, and can’t start with a number. It has to be a new table: uploading onto an existing name fails. 4. **Load it** Click **Load data**. When it’s done, Explore opens the new table so you can check it in **Preview Data**. > **Tip: Keep uploads tidy** > > In a DuckDB warehouse, click **New schema** first and make one for uploads, like `uploads`. Your own files stay apart from synced data. ## Uploading into Postgres An upload into Postgres runs as the data source’s own login, and that login needs permission to create tables. A read-only user (the kind we recommend for day-to-day queries) can’t, so the upload fails with a permission error. Upload into your DuckDB warehouse instead, or add a second data source that logs in as a user that can create tables. Postgres uploads load every column as text. To use a column as a number or a date, convert it in your query (for example `amount::numeric`), or in a [data model](https://tini.so/docs/data-models)’s expression. ## Updating an upload An upload is a snapshot. To bring in a newer export, upload it under a new table name, or drop the old table with SQL and upload again. For data that changes often, a [sync](https://tini.so/docs/data/sync) keeps it fresh for you. --- Previous: [Orcabase-hosted databases](https://tini.so/docs/data/hosted.md) · Next: [Sync data](https://tini.so/docs/data/sync.md) All docs: https://tini.so/llms.txt --- # Sync data > Copy data from Google Sheets, MySQL and hundreds of apps into your warehouse on a schedule: how syncs run, their statuses, and who manages them. Source: https://tini.so/docs/data/sync Some data can’t be queried where it lives: spreadsheets, databases Orcabase doesn’t connect to directly, and business apps. **Sync data** copies it into your warehouse and keeps the copy up to date on a schedule. Synced tables work like any other: in Explore, the SQL Editor, data models and the agent. ## Built-in syncs and Fivetran One page, two engines underneath. You pick the source; Orcabase picks the engine. Each source in the list is labeled “Built-in” or “via Fivetran”. | Engine | Sources | Where the data lands | | --- | --- | --- | | Built into Orcabase | [Google Sheets](https://tini.so/docs/data/google-sheets) and [MySQL](https://tini.so/docs/data/mysql) | Your DuckDB warehouse, one schema per source | | [Fivetran](https://tini.so/docs/data/fivetran) | Hundreds of apps and databases: Salesforce, HubSpot, Stripe, Google Ads and more | A hosted Postgres server, one schema per source | When Orcabase has its own connector for something, the catalog offers that one and hides Fivetran’s: built-in MySQL covers MySQL, MariaDB and Aurora, and PostgreSQL and BigQuery are [connected directly](https://tini.so/docs/data) instead of synced. ## Who can do what Everyone in your organization can see the Sync data page and every source’s status. Adding, changing, running and removing sources is for **admins**, since syncs write into your warehouse (and Fivetran syncs count against a monthly allowance). ## Add a source 1. **Open the catalog** Go to **Sync data → Add source**. Built-in connectors are listed first, then databases you can query directly, then everything Fivetran offers. 2. **Connect** Fill in the source’s details, pick the warehouse to sync into under **Sync into**, and click **Connect**. Orcabase checks the connection and lists the tables it found. See the page for each source: [Google Sheets](https://tini.so/docs/data/google-sheets), [MySQL](https://tini.so/docs/data/mysql), [Fivetran](https://tini.so/docs/data/fivetran). 3. **Choose tables and a schedule** Tick the tables to sync. Tick **Also sync tables added later** to pick up new ones automatically. Then set a **Name**, the **Schema** the tables go in (lowercase letters, digits and underscores), and how often to **Sync**. 4. **Start syncing** Click **Start syncing**. The first sync starts right away, and usually takes a couple of minutes. ## How a built-in sync works - **A full copy every time.** Each sync rebuilds every selected table from the source. The new copy swaps in all at once, so queries never see a half-loaded table. - **Failures are safe.** If a sync fails, the previous copy stays in place. If one table fails (say, it was deleted at the source), the others still sync and the source shows *Some tables failed*. - **On your schedule.** Every 15 minutes, 30 minutes, 1 hour, 3 hours, 6 hours (the default), 12 hours or once a day. **Sync now** runs one immediately. - **Passwords are encrypted**, and never shown again after you save them. ## Statuses | Status | What it means | | --- | --- | | Waiting for first sync | The source is set up; its first sync hasn’t finished yet. | | Syncing | A sync is running now. | | Up to date | The last sync finished without errors. | | Some tables failed | Most tables synced, but at least one didn’t. Open the source to see which, and why. | | Failed | The last sync didn’t finish. The previous copy of the data is still there. | | Needs reconnecting | Orcabase can’t sign in to the source any more. Update its connection details (or, for Fivetran, click Reconnect). | | Finish setup | A Fivetran source whose sign-in wasn’t completed. Click Finish setup. | | Paused | Someone paused it. Resume it from its menu. | | Paused: limit reached | Your organization used this month’s Fivetran allowance. See Fivetran. | ## Manage a source Open a source to see when it **Last synced**, its **Next sync**, and its **Recent syncs**, each with the rows and tables it copied. From the source (or its **⋯** menu in the list), admins can: - **Sync now**, or **Pause** and **Resume** it. - **Choose tables** to add or remove tables, and change how often it syncs. - Update its connection details. Orcabase tests them before saving. - **Remove** it. Syncing stops, but the tables already synced stay in the warehouse; drop them with SQL if you don’t need them. > **Tip: Finding synced tables** > > Synced tables live in the schema you chose, so a sheet synced into `sheets` shows up as `sheets.orders`. In [Explore](https://tini.so/docs/explore), open your warehouse, then that schema. --- Previous: [Upload files](https://tini.so/docs/data/upload-files.md) · Next: [Google Sheets](https://tini.so/docs/data/google-sheets.md) All docs: https://tini.so/llms.txt --- # Google Sheets > Sync a Google Sheet into your warehouse: share it with Orcabase, paste the link, and every tab becomes a table that refreshes on a schedule. Source: https://tini.so/docs/data/google-sheets Sync a Google Sheet into your warehouse, and every tab becomes a table you can query, chart and ask about. The copy refreshes on a schedule, so the numbers in Orcabase follow the sheet. ## Before you start - The Google Sheet, and permission to share it. - A DuckDB warehouse in Orcabase for the data to land in. See [Hosted by Orcabase](https://tini.so/docs/data/hosted). - The **Admin** role in your organization. ## Sync a spreadsheet 1. **Pick Google Sheet** Go to **Sync data → Add source** and pick **Google Sheet**, under **Built into Orcabase**. 2. **Share the sheet with Orcabase** The form shows an email address with a copy button. In Google Sheets, click **Share** and add that address as a **Viewer**. Orcabase reads the sheet as that address; it never needs to edit. 3. **Paste the link** Copy the spreadsheet’s link from your browser (it starts with `https://docs.google.com/spreadsheets/d/`) into **Spreadsheet link**. Pick your warehouse under **Sync into**, then click **Connect**. 4. **Choose tabs and a schedule** Orcabase lists the tabs it found. Tick the ones to sync, and tick **Also sync tabs added later** if you want new tabs picked up automatically. Set the **Schema** (for example `sheets`) and how often to sync, then click **Start syncing**. ## How tabs become tables | In the sheet | In Orcabase | | --- | --- | | Each tab | A table named after the tab, in lowercase with accents folded: `Đơn hàng` becomes `don_hang`, `Orders 2025` becomes `orders_2025`. | | The first row | The column names, kept as written. | | A blank column name | Named by position, like `column_3`. | | The same column name twice | The second gets a number, like `Amount_2`. | | Cell values | Types are detected from the data: numbers, dates, true/false and text. | Column names keep their spaces and capitals, so in SQL put names like that in double quotes: ```sql SELECT "Order Date", SUM("Amount") AS revenue FROM sheets.orders GROUP BY "Order Date" ``` ## Tips for sheets that sync well - Put the column names in row 1, with the data right under them. Titles or notes above the header become data. - Keep one kind of value per column: a column of amounts shouldn’t have “n/a” in it. - Give each dataset its own tab rather than stacking two tables in one. - Use short, plain column names, like `order_date`, so SQL doesn’t need quotes. > **Note** > > If you stop sharing the sheet with Orcabase’s address, the next sync can’t read it and the source shows an error. Share it again to resume. If the Google Sheet option shows as unavailable, Sheets syncing isn’t set up on your plan yet: message us. --- Previous: [Sync data](https://tini.so/docs/data/sync.md) · Next: [MySQL](https://tini.so/docs/data/mysql.md) All docs: https://tini.so/llms.txt --- # MySQL > Sync tables from MySQL, MariaDB or Aurora into your warehouse on a schedule with a read-only user: setup steps, limits and how it works. Source: https://tini.so/docs/data/mysql Orcabase copies tables from a MySQL database into your DuckDB warehouse on a schedule. It works for MySQL, MariaDB and Amazon Aurora (MySQL). Unlike Postgres, MySQL is synced rather than queried live. ## Before you start - The database’s host, port (usually 3306) and database name. - A user Orcabase can log in as. A read-only user is enough (below). - The database has to accept connections from the internet. If it only allows known IP addresses, [message us](https://linkedin.com/company/tinilab) for the address to allow. - A DuckDB warehouse in Orcabase to sync into, and the **Admin** role in your organization. ## Create a read-only user ```sql CREATE USER 'orcabase_readonly'@'%' IDENTIFIED BY 'choose-a-long-random-password'; GRANT SELECT ON your_database.* TO 'orcabase_readonly'@'%'; ``` > **Important: No spaces or quotes** > > The host, database, username and password can’t contain spaces or quote marks (`'` or `"`). Pick a password without them. ## Sync the database 1. **Pick MySQL** Go to **Sync data → Add source** and pick **MySQL**, under **Built into Orcabase**. 2. **Enter the connection details** Fill in **Host**, **Port**, **Database**, **Username** and **Password**, pick your warehouse under **Sync into**, and click **Connect**. Orcabase connects from the warehouse itself, so a successful connect means syncs will work too. 3. **Choose tables and a schedule** Tick the tables to sync, choose a **Schema** (for example `shop`) and a frequency, then click **Start syncing**. ## How it works - Each sync copies every selected table in full and swaps the new copy in at once. See [How a built-in sync works](https://tini.so/docs/data/sync#how-it-works). - Orcabase only reads from MySQL. Nothing is ever written back. - Addresses that point inside Orcabase’s own network (like `localhost` or private IP ranges) are refused. Use your database’s public address. - Very large tables take longer, since each sync copies them in full. Sync only the tables you need, and sync big ones less often. --- Previous: [Google Sheets](https://tini.so/docs/data/google-sheets.md) · Next: [More apps with Fivetran](https://tini.so/docs/data/fivetran.md) All docs: https://tini.so/llms.txt --- # More apps with Fivetran > Bring in Salesforce, HubSpot, Stripe, Google Ads and hundreds more through Fivetran, with a monthly allowance and table-by-table control. Source: https://tini.so/docs/data/fivetran For everything Orcabase doesn’t connect to itself, there’s Fivetran: hundreds of connectors for apps like Salesforce, HubSpot, Stripe and Google Ads, plus many more databases and file stores. Orcabase sets Fivetran up for you and keeps the synced data in a Postgres server it hosts, so it’s ready to query like everything else. ## Before you start - A [hosted Postgres server](https://tini.so/docs/data/hosted) connected as a data source. Fivetran writes into it. - The **Admin** role in your organization. - A login for the app you’re connecting. You sign in on Fivetran’s page, never in Orcabase. You don’t need a Fivetran account: Orcabase uses its own. ## Connect an app 1. **Pick the app** Go to **Sync data → Add source** and search for the app. Fivetran’s connectors are marked **via Fivetran**. 2. **Choose where it goes** Pick the Postgres data source to sync into and a **Schema** name for this app’s tables, like `stripe`. The first time, Orcabase sets Fivetran up on that database: it creates a separate user that can only add new schemas, and can’t touch your existing ones. 3. **Sign in on Fivetran** Click **Continue to Fivetran**. Fivetran’s page asks you to sign in to the app, or for its API key. Your login goes to Fivetran directly; Orcabase never sees it. 4. **Pick tables, then start** Back in Orcabase, choose which tables to sync and click **Save and start syncing**. Only the tables you pick are synced, and only they count toward your allowance. If you leave Fivetran’s page before finishing, the source waits with the status **Finish setup**. Click it to pick up where you left off. ## Your monthly allowance Fivetran charges by **monthly active rows**: each distinct row added, changed or deleted in a calendar month counts once, however often it changes. The first full load of a source and any re-syncs are free. Your organization gets a monthly allowance of these rows, and a few other limits: | Limit | Standard | What happens at the limit | | --- | --- | --- | | Monthly active rows | 500,000 a month | Syncing pauses until the next month, or until the limit is raised | | Sources | 5 | You can’t add another until you remove one | | How often each source syncs | Every 6 hours at most | Faster options aren’t offered | These are the standard limits; yours may differ with your plan. The Sync data page shows a bar with this month’s usage against the allowance, turning amber at 80%, and each source’s rows this month. > **Important: Usage updates every so often** > > Fivetran reports usage in batches, and Orcabase checks every 15 minutes, so a busy source can go a little over the allowance before it pauses. Syncing resumes by itself at the start of the next month (in UTC), or as soon as the limit is raised. To use less of the allowance: - **Sync fewer tables.** A table that isn’t synced costs nothing, so this matters most. Use **Choose tables** on any source. - New tables that appear in the app later stay off until someone turns them on, while new columns in tables you already sync come through. - Syncing less often helps less than you’d think: a row that changes 20 times in a month still counts once. ## Manage a Fivetran source - **Sync now**, **Pause** and **Resume** work as for built-in sources. Resuming and syncing now aren’t possible while the allowance is used up. - **Reconnect** appears when Fivetran can no longer sign in to the app, for example after a password change. It reopens Fivetran’s sign-in page. - **Remove** stops syncing and deletes the source from Fivetran. The tables already synced stay in your Postgres server. Synced tables show up in their own schema, like `stripe.charges`, everywhere in Orcabase. Orcabase also adds a free Fivetran usage schema (`fivetran_metadata`) to the database, which it reads to count your rows. --- Previous: [MySQL](https://tini.so/docs/data/mysql.md) · Next: [Explore](https://tini.so/docs/explore.md) All docs: https://tini.so/llms.txt --- # Explore > Browse every schema, table and column you’ve connected, preview real rows, profile columns, and start a query or data model from any table. Source: https://tini.so/docs/explore **Explore** is where you find out what data you have. It lists every data source in your organization, with its schemas, tables and columns, and shows you real rows before you write a single query. ## Browse your data Open **Explore** in the sidebar. The tree on the left has three levels: data sources, their schemas (groups of tables), and tables. Click to open each level; tables load when you open their schema, so even very large databases stay quick. The box above the tree filters what’s already open by name. Your place is saved in the page’s address, so a refresh, or a link you send a teammate, opens the same table. ## A data source Select a data source to see its schemas and details. Depending on the kind of source, you can also: - **New query**: start a query on this data source. - **Load data** (DuckDB and Postgres): turn a file into a table. See [Upload files](https://tini.so/docs/data/upload-files). - **New schema** (DuckDB): add a schema to organize tables. - **Attachments** (DuckDB): query a Postgres data source from this warehouse. See [Attach a Postgres database](https://tini.so/docs/data/hosted#attach-postgres). ## A table Select a table to see it from four angles: | Tab | What it shows | | --- | --- | | Overview | Where the table lives, and its columns at a glance. | | Columns | Every column with its type and whether it can be empty. | | Profile | DuckDB only. For each column: minimum, maximum, approximate number of unique values, average, spread and the share of empty values. A quick way to spot gaps and oddities. | | Preview Data | The first 100 rows, so you can see real values, formats and codes. | And two actions: - **Query this table** opens a new query that selects from it. Run it with **⌘↵** (Ctrl+Enter on Windows). - **Create data model** drafts a [data model](https://tini.so/docs/data-models) from the table’s columns, for you to review and save. > **Tip: Ask the agent instead** > > “What data do we have, and what does each table hold?” is a good first question for the [Data Agent](https://tini.so/docs/agent). It reads the same schemas and previews, and sums them up in plain words. --- Previous: [More apps with Fivetran](https://tini.so/docs/data/fivetran.md) · Next: [SQL Editor](https://tini.so/docs/sql-editor.md) All docs: https://tini.so/llms.txt --- # SQL Editor > A scratchpad for running SQL against any data source, with autocomplete, run selection and formatting. Save what works as a query. Source: https://tini.so/docs/sql-editor The **SQL Editor** is a scratchpad for running SQL against any of your data sources. Nothing is saved until you choose to save it, so it’s the place to try things out. ## Run SQL 1. Open **SQL Editor** in the sidebar and pick a data source. 2. Write your SQL. Autocomplete suggests keywords, table names and the columns of tables your query mentions. 3. Click **Run**, or press ⌘ ↵ (Ctrl Enter on Windows). The result appears below the editor. Drag the divider to give either more room. To run just part of a script, highlight it: the button changes to **Run selection**. **Beautify** tidies the SQL up, with one clause per line and keywords in capitals. ## Write SQL for your database Each data source speaks its own flavor of SQL, and Orcabase sends your SQL to it as written. The main differences you might notice: | Data source | Dialect | Example: revenue by month | | --- | --- | --- | | PostgreSQL | PostgreSQL | `date_trunc('month', created_at)` | | BigQuery | BigQuery Standard SQL | `DATE_TRUNC(DATE(created_at), MONTH)` | | DuckDB | DuckDB (close to PostgreSQL) | `date_trunc('month', created_at)` | Every query returns at most 5,000 rows and stops after 30 seconds. For bigger questions, add up in SQL (with `GROUP BY`) rather than pulling raw rows. ## Save it When a query is worth keeping, click **Save as query**. It becomes a saved query that you can name, chart and pin to dashboards. See [Queries](https://tini.so/docs/queries). ## Keyboard shortcuts | Keys | Does | | --- | --- | | ⌘ ↵ | Run the query, or the highlighted part | | ⌘ S | Save (on a saved query’s page) | | Ctrl Space | Show autocomplete suggestions | On Windows and Linux, use Ctrl in place of ⌘. --- Previous: [Explore](https://tini.so/docs/explore.md) · Next: [Queries](https://tini.so/docs/queries.md) All docs: https://tini.so/llms.txt --- # Queries > Save SQL as a query, add parameters with {{ name }}, and give it a chart. How results are kept, and how metric queries differ from SQL. Source: https://tini.so/docs/queries A **query** is a saved question for one data source. It holds the SQL, an optional description, and at most one chart. Saved queries are what dashboards and notebooks are made of. ## Create a query There are a few ways to start one: - **Queries → New query** opens an empty query on your organization’s first data source. Change the data source from the picker next to the editor. - **Save as query** in the [SQL Editor](https://tini.so/docs/sql-editor). - **Query this table** in [Explore](https://tini.so/docs/explore). - Ask the [agent](https://tini.so/docs/agent) to save a chart: it saves the query behind it. The **Queries** page lists every saved query with its data source, who created it and when it last ran. ## The query page - **Name and description.** Click the title to rename it. The description is optional: on dashboards, a chart shows an info icon that reveals it, so use it to say what the number means. - **Run** (⌘ ↵) runs the query. **Save** (⌘ S) saves your changes. Changing the data source saves right away. - **Data Preview** shows the result as a table; **Chart** turns it into a chart. See [Charts](https://tini.so/docs/charts). - **Delete query** is in the **⋯** menu. Dashboards that show its chart lose that widget. ## Results A query returns at most 5,000 rows and stops after 30 seconds. Orcabase keeps the latest result of every saved query, and dashboards show that saved result, so they open instantly without running anything. A result is replaced each time the query runs; older results aren’t kept. ## Parameters A parameter is a blank in your SQL that you fill in before running it. Write it as `{{ name }}`: ```sql SELECT date_trunc('week', created_at) AS week, SUM(amount) AS revenue FROM orders WHERE country = {{ country }} AND created_at >= {{ since }} GROUP BY week ORDER BY week ``` A box for each parameter appears above the editor. Type the values (`VN`, `2025-01-01`) and run. Values are text: the database converts them where the SQL expects a number or a date. ### How values are sent | Data source | How a value reaches the database | | --- | --- | | PostgreSQL | As a real query parameter, separate from the SQL | | BigQuery | As a named query parameter, separate from the SQL | | DuckDB | Inserted into the SQL as quoted text. It’s escaped, so it can’t break out of the quotes, but it always arrives as text: use `CAST({{ n }} AS INTEGER)` where you need a number. | > **Note** > > Parameter values aren’t saved with the query. A dashboard shows the chart from the query’s last run, and **Run all queries** on a dashboard runs each query with its parameters empty. For dashboard charts, queries without parameters work best. ## Metric queries A query can also ask for [metrics](https://tini.so/docs/metrics) by name instead of holding SQL: revenue and orders, by month, last 90 days. Orcabase writes the SQL each time it runs, from the current metric definitions, so the chart stays right when a definition changes. See [Explore and query metrics](https://tini.so/docs/metric-queries). --- Previous: [SQL Editor](https://tini.so/docs/sql-editor.md) · Next: [Charts](https://tini.so/docs/charts.md) All docs: https://tini.so/llms.txt --- # Charts > The 16 chart types, from Number and Line to Funnel and Heatmap, and how to set up their data, display and number format in Orcabase. Source: https://tini.so/docs/charts Every saved query can have one chart. The chart is drawn from the query’s latest result, and it goes wherever the query goes: onto dashboards, into notebooks, and into public share links. ## Add a chart to a query 1. **Run the query** Charts are built from a result, so run the query first. 2. **Open the Chart tab** Next to **Data Preview**, open **Chart** and pick a **Chart type**. Orcabase fills in sensible columns to start with: the first text or date column along the axis, the number columns as values. 3. **Adjust and save** Change the settings on the right (below), watching the preview, then click **Save chart**. On a dashboard, the sliders button on a chart opens the same settings in place. A query has one chart; to show the same data two ways, save the SQL as a second query. > **Tip: Shape the result for the chart** > > Return one label or date column first, then one column per number, with readable names: `month`, `revenue`, `orders`. Most charts then need no setting up at all. ## Chart types | Type | Use it for | | --- | --- | | Number | One headline value, with an optional change and trend line | | Progress | A value against a goal, as a bar | | Gauge | A value against a goal, as a dial | | Line | Change over time | | Area | Volume over time | | Column | Comparing categories, as vertical bars | | Bar | Ranking categories, as horizontal bars. Good for long labels | | Combo | Bars and lines on one axis, like revenue with an order count | | Scatter | How two numbers relate | | Pie | Shares of a whole, with a few slices | | Donut | Shares of a whole, with the total in the middle | | Funnel | Drop-off between stages, like visit → sign-up → purchase | | Treemap | Shares of many categories | | Radar | A profile across several dimensions | | Heatmap | A number across two dimensions, like orders by weekday and hour | | Table | Every column as it is | ## Chart settings Settings are grouped in three tabs. Each chart type shows only the settings that apply to it. ### Data - **X axis** and **Y axis**: which column runs along the bottom, and which columns are drawn. You can pick several value columns. - **Split by**: one line or bar per distinct value of a column, like one line per plan. - For a **Number**: the **Value** column, which row to **Read from** (first or last), **Compare with previous row** to show the change, and a **Sparkline** of the trend across all rows. - For **Progress** and **Gauge**: a **Goal**, either from a column or a fixed number. - For **Combo**: tick **Draw as line** for the columns that should be lines; the rest are bars. - For **Pie**, **Donut**, **Funnel** and **Treemap**: the category and value columns, and a maximum number of slices or stages. ### Display **Stacking** (none, stacked or 100%), **Line style** (smooth, straight or step), **Show points**, **Legend**, **Value labels**, **Gridlines**, **Sort** (query order, largest first or smallest first) and axis titles. ### Format **Number style**: automatic, number (1,234.5), compact (1.2K), percent (25%) or currency ($1,234), plus the **Currency**, **Decimals**, a **Prefix** and a **Suffix**. Percent multiplies by 100, so a value of 0.25 shows as 25%. ## Big results To stay fast, charts draw a sample of very large results and say so under the chart, like “Sampled 400 of 5,000 points”: | Chart | Draws at most | | --- | --- | | Line and area | 400 points per line, sampled so the shape is kept | | Column | The first 100 bars | | Bar | The first 30 bars | | Scatter | 500 points | | Heatmap | 60 columns by 40 rows | | Table on a dashboard | 200 rows | Series use eight colors chosen to stay distinguishable for people with color blindness. From the ninth series on, the rest are grouped as “Other”. If you’re hitting these limits, add up more in SQL, or use **Sort** and the top slices to focus on what matters. See also [Limits](https://tini.so/docs/limits). --- Previous: [Queries](https://tini.so/docs/queries.md) · Next: [Notebooks](https://tini.so/docs/notebooks.md) All docs: https://tini.so/llms.txt --- # Notebooks > Write queries and build charts in one scrolling document, add notes between them, then pin the charts to any dashboard in Orcabase. Source: https://tini.so/docs/notebooks A **notebook** is one scrolling document for working through an analysis: SQL cells with their results and charts right underneath, and text cells for headings and notes. When a chart is ready, pin it to any dashboard without leaving the page. ## Build a notebook 1. **Create it** Go to **Notebooks → New notebook**. Click the title to name it. 2. **Add a SQL cell** Click **SQL cell**. Each cell has its own data source (pick it in the cell’s header), its own SQL and its own result. Run it with **Run**. 3. **Chart the result** Click **Set chart** under a result to add a chart, built from that cell’s columns. **Edit chart** changes it later. 4. **Add notes** Click **Text cell** for a heading or a few lines of explanation between charts. 5. **Pin charts to dashboards** Click **Add to dashboard** on a chart and pick a dashboard. You can pin the same chart to several dashboards, then move and resize it there. Hover over a cell to show **Move up**, **Move down** and **Delete cell**. ## How cells work - Each SQL cell is a saved [query](https://tini.so/docs/queries), so it also appears on the **Queries** page, and its chart can go anywhere a query’s chart can. - Cells run one at a time, each against its own data source. A cell can’t read another cell’s result. - Notebooks are for one person at a time: two people editing the same notebook at once can overwrite each other. > **Important: Deleting a cell deletes its query** > > Because each SQL cell is a query, deleting the cell (or the whole notebook) deletes those queries everywhere, and their charts disappear from every dashboard they’re pinned to. Keep the cells behind charts you still use. ## Notebooks or dashboards? Use a notebook to work something out: try queries, compare charts, write down what you found. Use a [dashboard](https://tini.so/docs/dashboards) for the numbers people check again and again. Most dashboards start life as a notebook. --- Previous: [Charts](https://tini.so/docs/charts.md) · Next: [How metrics work](https://tini.so/docs/semantic-layer.md) All docs: https://tini.so/llms.txt --- # How metrics work > Why Orcabase asks you to define each number once, and how data models, metrics and metric queries fit together to keep answers consistent. Source: https://tini.so/docs/semantic-layer Ask three people what “revenue” means and you can get three answers: every order, only paid orders, or paid orders minus refunds. A chart built on the wrong one looks just as convincing as the right one. So does an AI answer. The fix is to write each definition down once, check it, and have everything use it. In Orcabase, that’s the **semantic layer**: **data models** and **metrics**. 1. **Data model**: `orders`. Group by created_at and plan. Add up paid_amount. 2. **Metric**: Revenue ✓. Sum of paid order amounts, refunds excluded. Certified by Finance. 3. **Metric query**: Revenue by month. Last 90 days, split by plan. 4. **Result**: A chart, anywhere. The same number on dashboards, in the agent and in Claude. A metric is asked for by name. Orcabase writes the SQL for your database each time, from the current definitions. ## The three pieces - A [data model](https://tini.so/docs/data-models) describes one table in business terms: what you can group and filter by (**dimensions**, like order date, plan or country), what you can add up or count (**measures**, like paid amount or number of orders) and how it joins to other tables. - A [metric](https://tini.so/docs/metrics) is a named business number built on a model’s measure, with a description, an owner and a format: *Revenue*, *Average order value*, *Net revenue*. Someone checks it and clicks **Certify**, and it becomes the definition everyone uses. - A [metric query](https://tini.so/docs/metric-queries) asks for metrics by name: Revenue, by month, split by plan, last 90 days. Orcabase writes the SQL for your database from the current definitions. ## Why it’s worth the few minutes - **One number everywhere.** Dashboards, notebooks, the Data Agent and Claude or ChatGPT all get Revenue from the same definition, so they agree. - **Fix it once.** Saved metric queries store the metric’s name, not SQL. Change the definition and every chart that uses it is right on its next run. - **Better AI answers.** The agent checks your certified metrics first, and says which definition it used. Without them, it has to guess what your columns mean from their names. - **Clear ownership.** Every change is recorded with who made it, and a certified metric shows who vouched for it. ## Correct or loud, never wrong Some questions can’t be answered safely from a model. The classic case: adding up order amounts while splitting by product, when each order has several products, counts every order once per product and inflates revenue. Orcabase checks each join’s relationship, and refuses a query like that with an explanation instead of returning a plausible wrong number: > **Note: For example** > > *orders can’t be grouped or filtered by order_items: the path orders → order_items crosses a one-to-many join and would double-count. Define the metric on order_items.* ## Get started The quickest start is to ask the agent: “Model our orders table and draft a revenue metric.” It reads the table, drafts a model and a metric, and tests them. You review and certify. To do it by hand, start from [a table in Explore](https://tini.so/docs/data-models#create). - [Data models](https://tini.so/docs/data-models): Dimensions, measures and joins. - [Metrics](https://tini.so/docs/metrics): Define, certify and govern your key numbers. --- Previous: [Notebooks](https://tini.so/docs/notebooks.md) · Next: [Data models](https://tini.so/docs/data-models.md) All docs: https://tini.so/llms.txt --- # Data models > Describe a table once: the dimensions to group by, the measures to add up, and how it joins to others. Scaffold a model from any table. Source: https://tini.so/docs/data-models A **data model** describes one table in business terms, once: what people can group and filter by, what they can add up, and how it connects to other tables. Metrics are built on top of data models. You’ll find them under **Semantic layer → Data Models**. ## Create a data model The fastest way is to start from a table, and let Orcabase draft the model for you: 1. **Start from a table** In **Explore**, open the table and click **Create data model**. Or, on the Data Models page, choose **New → New data model from a table**. 2. **Review the draft** Orcabase reads the table’s columns and drafts a starting point: - date and time columns become time dimensions, and the first becomes the default time dimension; - text, true/false and low-variety columns become dimensions; - number columns that aren’t IDs become measures that add up (sum); - a count of rows is always added; - columns like `user_id` that match another table’s name are suggested as joins. Nothing is saved yet. Remove what you don’t need, rename things, and add descriptions. 3. **Create it** Click **Create**. Orcabase checks every expression against your database as it saves. For data that isn’t one table, choose **New → New data model from SQL** and write a `SELECT` whose result becomes the model, for example sessions built from raw events. ## Overview | Field | What it’s for | | --- | --- | | Name | How metrics and queries refer to the model, like `orders`. Unique in your organization. | | Label and description | How it’s shown to people, and what it means. | | Source | A table (schema and table name) or SQL. | | Primary key | The column or columns that identify a row, like `id`. | | Default time dimension | The date that metrics on this model trend over, unless you pick another. | ## Dimensions A dimension is something to group or filter by: order date, plan, country. Each has a **Type** (time, text, number or true/false) and an **Expression**: the column, or any SQL expression over the table’s columns. Time dimensions list the **Time grains** they allow: day, week, month, quarter, year. Tick **Hidden** to keep a dimension out of pickers. ```text country upper(shipping_country) is_repeat order_number > 1 created_at created_at ``` ## Measures A measure is something to add up or count. Pick an **Aggregation** (count, count distinct, sum, average, min or max) and an **Expression** to aggregate. An optional **Filter** limits which rows count, which is how “paid revenue” differs from “all order value”: | Name | Aggregation | Expression | Filter | | --- | --- | --- | --- | | `order_count` | count | | | | `paid_amount` | sum | `amount` | `status = 'paid'` | | `buyers` | count distinct | `customer_id` | | The **Used by** column shows which metrics rely on each measure. A measure that a metric uses can’t be deleted. ## Joins A join connects this model to another on the same data source: pick the other **Data model**, the **Relationship**, and the **Join condition**, like `orders.customer_id = customers.id`. Then metrics on orders can be split by the customer’s plan or country. | Relationship | Means | Example | | --- | --- | --- | | many → one | Many rows here match one row there | Many orders, one customer | | one → one | Each row matches at most one row there | A customer and their settings | | one → many | One row here matches many rows there | One order, many order items | > **Important: Get the relationship right** > > Orcabase uses it to avoid double-counting: it won’t split a measure across a one → many join, because each row would be counted once per match. Declaring a join as many → one when it’s really one → many can produce wrong numbers. ## Checks and the Broken badge Every save checks the model against your database, without reading any rows: each column, function and type in every expression has to resolve. Problems show next to the dimension or measure that caused them. If the table changes later (say a column is renamed), the model shows a **Broken** badge, with the details one click away, and metric queries on it fail until you fix it. If the database can’t be reached, Orcabase still saves and tells you it couldn’t check. ## History and lineage - **History** keeps every saved version with who changed it and when. **Restore this version** brings an old one back. - **Lineage** shows the metrics built on this model. - Renaming a model or a field updates the metrics and saved metric queries that use it, so nothing breaks. - A model that metrics use, or that other models join to, can’t be deleted; the error lists what’s in the way. ### Current limits - A model lives on one data source, and joins only connect models on the same data source. - Time grains are counted in UTC: a “day” runs from midnight to midnight UTC. Next: build [metrics](https://tini.so/docs/metrics) on your model. --- Previous: [How metrics work](https://tini.so/docs/semantic-layer.md) · Next: [Metrics](https://tini.so/docs/metrics.md) All docs: https://tini.so/llms.txt --- # Metrics > Define revenue, churn and your other key numbers once, then certify them: simple, ratio and derived metrics, formats, lineage and history. Source: https://tini.so/docs/metrics A **metric** is one of your business numbers, defined once: Revenue, Average order value, Net revenue. Dashboards, notebooks, the agent and your AI assistant all use the same definition, so everyone gets the same number. You’ll find them under **Semantic layer → Metrics**. ## Three kinds of metric | Kind | What it is | Example | | --- | --- | --- | | Simple | One measure from a data model, with an optional extra filter | Revenue = sum of paid order amounts | | Ratio | One metric divided by another. Each is added up first, then divided, so it’s never an average of averages | Average order value = Revenue ÷ Orders | | Derived | A formula over other metrics | Net revenue = Revenue − Refunds | Metrics are built on [data models](https://tini.so/docs/data-models), so set one up first. For now, a ratio or derived metric can only be queried when all of its parts come from the same data model. ## Create a metric 1. **Start one** Go to **Metrics → New metric**. Or ask the agent: “Draft a revenue metric from paid orders.” 2. **Define it** On **Definition**, pick the kind. For a simple metric, choose the **Data model** and **Measure**, and add an **Extra filter** if you need one. For a ratio, pick the **Numerator** and **Denominator** metrics. For a derived one, write the **Formula**, inserting metrics by name. 3. **Describe it** On **Details**, give it a **Label** and a **Description**: say what it means and what it leaves out (“Paid orders, excluding refunds and tax”). Set how it’s shown (below). 4. **Create it and check it** Click **Create**. The **Explore** tab charts the metric over time from real data. Check it against a number you trust. ## Details | Setting | What it does | | --- | --- | | Number format | Auto, number (1,234.5), compact (1.2K), percent (25%) or currency ($1,234), with the currency and decimals. Charts of the metric use it. | | Good direction | Up is good, down is good, or neutral. Colors changes green or red, so a drop in churn shows as good news. | | Default time grain | The step it trends by unless someone picks another: day, week, month, quarter or year. | | Owner | Who to ask about this number. | | Tags | Comma-separated labels for finding it, like `finance, kpi`. | ## Draft, certified, deprecated Every metric has a status, shown as a badge wherever it appears: | Status | Means | | --- | --- | | Draft | New or changed, and not vouched for yet. Everything the agent creates starts here. | | Certified | Someone checked it and vouched for it. The agent prefers certified metrics. | | Deprecated | Still works, but marked as on its way out. Point people to its replacement. | - **Certify** appears on a saved metric that isn’t certified. The metric records who certified it and when. - **Editing a certified metric’s definition sends it back to draft**, so a changed formula is never still vouched for by someone who checked the old one. Descriptions and formats can change without that. - The **⋯** menu has **Return to draft**, **Deprecate** and **Delete metric**. > **Note: Who can certify** > > Any member of your organization can create, edit and certify metrics. People certify; the agent and AI assistants can only draft. ## Lineage and history - **Lineage** shows the data model the metric is built on, the metrics it uses, and the metrics that use it. - **History** keeps every saved version, with who changed it and when. **Restore this version** brings an old one back. - Renaming a metric updates the metrics and saved metric queries that refer to it. - A metric that other metrics build on can’t be deleted. Saved queries that ask for a deleted metric stop working, so when a metric is in use, deprecate it rather than deleting it. ## Where metrics show up - **Explore** tab on each metric: chart it by any time grain, split and filter it. See [Explore and query metrics](https://tini.so/docs/metric-queries). - **Saved queries** and dashboards, as metric queries that follow the definition. - **The Data Agent** checks your metrics before writing SQL, and says which one it used. - **Claude and ChatGPT**, through the `list_metrics` and `query_metrics` [tools](https://tini.so/docs/connect-ai/tools). > **Tip: A first set** > > For a subscription or online business, start with Revenue, New customers, Active customers, Churn rate and Average order value. That covers most Monday questions. --- Previous: [Data models](https://tini.so/docs/data-models.md) · Next: [Explore and query metrics](https://tini.so/docs/metric-queries.md) All docs: https://tini.so/llms.txt --- # Explore and query metrics > Ask for metrics by name, trend them by day, week or month, split and filter them, and save charts that follow the metric definitions. Source: https://tini.so/docs/metric-queries A **metric query** asks for metrics by name, instead of spelling out SQL: “Revenue and Orders, by month, split by plan, for the last 90 days.” Orcabase writes the SQL for your database from the current definitions every time it runs. ## Explore a metric Open any metric and go to its **Explore** tab. It charts the metric, and you can change the question with a few controls: | Control | What it does | | --- | --- | | Metrics | Add more metrics to see them side by side, like Revenue and Orders. | | Range | Last 7 days, 30 days, 90 days, 12 months, or all time. | | Trend by | The time grain: day, week, month, quarter or year. Or no trend, for a single total. | | Split by | Break the numbers down by a dimension, like plan or country. | | Where | Filters, like country is one of VN, SG. Numbers and dates also compare with >, ≥, < and ≤; text can match with contains. | Switch between the **Chart** and the **Table**, and click **SQL** to see exactly what ran. If you’ve edited the metric but not saved it, Explore still shows the saved definition. ## Save it as a query When the view is right, click **Save as query** and name it. It becomes a saved [query](https://tini.so/docs/queries) of the metric kind: give it a [chart](https://tini.so/docs/charts), pin it to a dashboard, or open it from the Queries page, where the same controls replace the SQL editor. Because a metric query stores names, not SQL, it follows the definitions: change how Revenue is calculated, and every saved metric query asking for Revenue picks up the change on its next run. Renaming a metric or a field updates saved metric queries for you. > **Note: Convert to SQL** > > Need something the controls can’t express? **Convert to SQL**, on a metric query’s page, turns it into an ordinary SQL query, starting from the SQL Orcabase wrote. It stops following the metric definitions from then on. ## What the result looks like Result columns are named after what you asked for, so charts map onto them naturally. Revenue by month, split by plan, comes back as: ```text created_at__month plan revenue 2025-06-01 Monthly 31,420 2025-06-01 Sampler 8,150 2025-07-01 Monthly 33,080 … ``` A time dimension at a grain is named `dimension__grain`, like `created_at__month`. ## Rules that keep numbers right - **No double-counting.** A metric can be split or filtered by its own model’s dimensions, and by models it reaches through many → one or one → one joins. Across a one → many join, Orcabase refuses and explains why. See [Correct or loud](https://tini.so/docs/semantic-layer#correct-or-loud). - **Clear errors.** Ask for a metric or field that doesn’t exist, or a grain a dimension doesn’t allow, and the error lists the valid options. - **Safe values.** Filter values are sent to the database as parameters, never pasted into the SQL. - **UTC time.** Grains and ranges are counted in UTC. “Last 30 days” is worked out when the query runs, so a saved query always means the most recent 30 days. - **The usual limits.** At most 5,000 rows, and 30 seconds. A fine grain over a long range with a split can hit the row limit: use a coarser grain or a shorter range. --- Previous: [Metrics](https://tini.so/docs/metrics.md) · Next: [Data Agent](https://tini.so/docs/agent.md) All docs: https://tini.so/llms.txt --- # Data Agent > Ask about your business in plain words and get the answer, a chart and how it got there. What the Data Agent can build, and its guardrails. Source: https://tini.so/docs/agent The **Data Agent** is an AI analyst that works on your real data. Ask it something in plain words. It looks at your metrics and tables, runs queries, checks what it finds, and answers with the numbers, a chart, and the steps it took. Open **Agent** in the sidebar to start. > **Note** > > An admin turns the agent on once, in Settings → Agent. Until then, the Agent page says it isn’t set up yet. See [Set up the agent](https://tini.so/docs/agent/setup). ## What an answer looks like An example answer, with illustrative numbers: > **You:** Why did revenue drop last week? > > **Agent:** **Revenue fell 13% last week, to $10.4k.** > > - **One-time orders** dropped from $5.9k to $4.3k after the free-shipping banner ended on Tuesday. > - **Subscriptions** held steady at $6.1k. > > [Chart card: Revenue by week ($k), stacked columns for subscriptions and one-time orders, with a chart-type menu, Customize and ⋯] > > How I got this: Checked the metrics · Ran 2 queries · 4 steps 1. **The answer first:** a headline and the few numbers that matter, in plain words. 2. **A chart you can change.** Switch the chart type from the card’s header, or click **Customize** for the same Data, Display and Format settings as [any chart](https://tini.so/docs/charts). Your changes stay on that card, and you can go back to the agent’s version. The **⋯** menu has **View SQL** and **Copy SQL**. 3. **How I got this**, folded away: every step in plain words, like “Checked the metrics” or “Ran a query · 3 rows”. Open it to check the agent’s work, SQL included. ## Asking good questions Ask the way you’d ask a colleague. A few that work well: | To | Try | | --- | --- | | Get your bearings | “What data do we have, and what does each table hold?” | | Check a number | “How much revenue did we make last month?” | | Find out why | “Why did revenue drop last week?” | | Compare | “Do customers who start with the sampler stay longer?” | | See your definitions | “Which certified metrics can I ask about?” | - **Name the period.** “Last week”, “in August”, “since we launched the sampler”. - **Follow up.** The agent remembers the chat: “Now split that by plan” works. - **Define your key numbers.** With certified [metrics](https://tini.so/docs/metrics), the agent uses your definitions instead of guessing from column names, and says which one it used. ## How it finds answers The agent works in steps, like an analyst would. For most questions it checks your certified metrics first, then your saved queries, and only writes new SQL when neither covers the question. Before writing SQL against a table, it reads the columns and a few sample rows. If a query fails, it reads the error, fixes the SQL and tries again. ### Long questions Each model call is one step, and your organization sets how many steps one question can take (30 unless an admin changed it). When a question needs more, the agent stops to sum up what it has done so far and asks: *This is taking a while. Keep going?* Click **Continue** to carry on, or **Stop here**. ## Building things Ask, and the agent builds it for you: - **Charts and dashboards:** “Put weekly revenue and new customers on a dashboard called Monday.” It saves each chart as a query, creates the dashboard (or uses the one with that name), and places the charts. - **Data models and metrics:** “Model our orders table and draft a revenue metric.” It checks what already exists, reads the table, writes a model with real descriptions, drafts the metric, and tests it. The answer links to everything it made. New metrics are always **drafts**: review them on the Metrics page and certify the ones you trust. > **Note: It creates, never edits or deletes** > > The agent can add new queries, dashboards, charts on a dashboard, data models and draft metrics. It has no way to edit or delete anything that exists, and it can’t certify metrics. It only builds when you ask. It doesn’t ask for approval first, so if it makes something you don’t want, delete it yourself. ## Choosing a model Your admin picks a default model and up to eight more. Pick one for your next question from the menu in the chat box; your choice is remembered in this browser. Each answer says which model wrote it, which makes it easy to compare them. ## Chats - Every chat is saved, with its charts, and has its own address. Open **Chat history** to find one: chats are grouped by Today, Yesterday, Previous 7 days and Older. - Your first question names the chat. Rename or delete it from the history. - A chat keeps working if you switch to another chat or leave the page, so a long question can finish while you do something else. - Chats are private: only the person who started a chat can see it. - The chat header shows how many tokens the chat has used, and its cost when your AI provider reports one. See [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage). --- Previous: [Explore and query metrics](https://tini.so/docs/metric-queries.md) · Next: [Set up the agent](https://tini.so/docs/agent/setup.md) All docs: https://tini.so/llms.txt --- # Set up the agent > Choose Orcabase AI or your own OpenRouter or Vercel AI Gateway key, pick the models your team can use, and set a step limit per question. Source: https://tini.so/docs/agent/setup The agent needs an AI model to think with. An admin chooses how it gets one, once, for the whole organization, under **Settings → Agent** “Admins”. Everyone in the organization can then use it. ## Two ways to run it | | Orcabase AI | Your own key | | --- | --- | --- | | What it is | Runs on Orcabase’s AI account | Runs on your OpenRouter or Vercel AI Gateway account | | Setup | Pick models. There’s no key to paste | Paste an API key, then pick models | | Models | The list Orcabase offers | Hundreds: anything the gateway offers | | Who pays for AI | Covered by a credit for your organization | You, directly to the gateway, at its prices | | Usage shown as | A percentage of your credit | Tokens and dollars | Orcabase AI appears first when it’s available for your organization. You can switch between the two at any time; a key you saved stays saved, so switching back doesn’t mean pasting it again. OpenRouter and Vercel AI Gateway are **gateways**: one account and one API key reach models from Anthropic, OpenAI, Google and others, on one bill. ## Set up your own key 1. **Get a key** Create an API key in your OpenRouter or Vercel AI Gateway account. Give it a spending limit there: it’s a second safety net on top of the limits in Orcabase. 2. **Paste it** In **Settings → Agent**, pick **OpenRouter** or **Vercel AI Gateway** as the **Provider** and paste the key into **API key**. 3. **Pick models** Choose a **Default model**, and up to eight **More models to try** that people can switch to. The picker is searchable, shows each model’s price per million tokens and how much text it can take in, and lists popular models first. It hides models that can’t use tools, since the agent needs them; you can also type any model id. 4. **Test and save** Click **Test and save**. Orcabase makes one tiny request with that key and each model before saving, so a wrong key or an unavailable model is caught now. *Saved. The key works.* means you’re done. > **Note: How the key is kept** > > The key is encrypted, used only to call the gateway, and never shown again: the page shows its last four characters. **Remove key** deletes it, and the agent stops until a new one is added. ## Set up Orcabase AI Pick **Orcabase AI** as the provider, choose a default model and any more models to try from Orcabase’s list, and save. There’s no key and nothing to test. Usage draws on a credit shared by your whole organization; see [Orcabase AI credit](https://tini.so/docs/agent/privacy-and-usage#orcabase-ai-credit). ## Steps per question Each call to the model is one step. **Steps per question** caps how many one question can take: between 5 and 100, 30 by default. At the limit the agent pauses and asks whether to keep going, so the limit controls cost without cutting answers off. Changing only this number saves without testing the models again. ## Usage The **Usage** card on the same page shows this month’s model calls, tokens and cost (or share of credit), broken down by model and by member. On Orcabase AI it also shows how much of today’s, this week’s and this month’s credit is used. See [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage). --- Previous: [Data Agent](https://tini.so/docs/agent.md) · Next: [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage.md) All docs: https://tini.so/llms.txt --- # AI privacy and usage > What the AI provider sees, what it never sees, and how tokens, costs and the Orcabase AI credit are counted for your organization. Source: https://tini.so/docs/agent/privacy-and-usage When you ask the agent a question, parts of the conversation are sent to an AI model. This page says exactly what, who receives it, and how usage is counted. ## What the AI model sees - Your questions, and the conversation so far. - The names of your data sources, schemas, tables and columns. - SQL, and the definitions of your data models and metrics. - **Small samples of results.** A result is cut to at most 30 rows and 16,000 characters before the model sees it. The agent is told to add things up in SQL, so it rarely needs raw rows. - Names of saved queries and dashboards, when it looks them up. ## What it never sees - Database passwords, service account keys and other credentials. - Data from other organizations. - Full results. Charts in the chat are drawn from up to 1,000 rows that go to your browser, not to the model. ## Who receives it Two companies handle each request: - **The gateway** (OpenRouter or Vercel AI Gateway) passes the request on. - **The model’s maker** (for example Anthropic, OpenAI or Google) runs the model. Their terms decide how long requests are kept and whether they’re used for training. With your own key, your own agreement with the gateway applies, including any data settings you choose there. With Orcabase AI, requests go through Orcabase’s OpenRouter account. > **Note** > > Chats are stored in Orcabase, with their charts, and only the person who started a chat can open it. ## How usage is counted Every call to a model is recorded: which model, who asked, in which chat, how many tokens went in and out, and the cost. Tokens are how AI providers measure text; a word is roughly one to two tokens. - **In a chat:** the header shows the chat’s total tokens, and its cost when the provider reports one. Tokens spent on an answer that failed or was stopped count too. - **In Settings → Agent:** the **Usage** card shows this month’s calls, tokens and cost (or share of credit) by model, and by member. On Orcabase AI it also shows today’s, this week’s and this month’s credit. - **On your own key,** costs are shown in dollars, and your gateway bills you directly. Its own dashboard is the final word on what you owe. ## Orcabase AI credit On Orcabase AI, everyone in your organization shares one credit. So that one busy day can’t use it all, it has three limits: | Limit | Resets | | --- | --- | | Daily | Every day at 00:00 UTC | | Weekly | Every Monday at 00:00 UTC | | Monthly | On the 1st of each month, at 00:00 UTC | - Usage is shown as a **percentage** of each limit. Once half of a limit is used, the chat header shows a badge, like “62% of today’s credit”, which turns amber at 80%. - When a limit is used up, the agent pauses and says which limit and when it resets. It picks up again after that. An answer already in progress can go slightly over. - How much credit your organization has depends on your plan. To change it, message us, or switch to your own key in [Settings → Agent](https://tini.so/docs/agent/setup). ## Keeping costs down - **Certified metrics** make answers shorter: the agent asks for a metric by name instead of exploring tables. - **Pick a smaller model** for simple questions. Every answer says which model it used, so it’s easy to compare quality. - **Steps per question** caps a single question, and the agent asks before going further. - **Start a new chat** for a new topic. Long chats send more history with each question. --- Previous: [Set up the agent](https://tini.so/docs/agent/setup.md) · Next: [Dashboards](https://tini.so/docs/dashboards.md) All docs: https://tini.so/llms.txt --- # Dashboards > Pin charts and notes onto a free-form grid your whole team sees: add widgets, arrange them, edit charts in place and keep numbers fresh. Source: https://tini.so/docs/dashboards A **dashboard** is one page with the numbers that matter: charts from your saved queries, and text notes, on a grid you arrange. Everyone in your organization sees the same dashboards, and you can share one publicly with a link. ## Build a dashboard 1. **Create it** Go to **Dashboards → New dashboard**. Click the title to name it, and add a description if it helps people know what they’re looking at. 2. **Add widgets** Click **Widgets**. Pick **Text** for a heading or a note, or any saved query that has a [chart](https://tini.so/docs/charts). The widget lands at the bottom of the grid. 3. **Arrange them** Hover over a widget and drag its handle to move it. Drag the bottom-right corner to resize it. Other widgets shift out of the way. The grid is four columns wide. Changes save as you go. Faster still: ask the [agent](https://tini.so/docs/agent) to “build a dashboard with weekly revenue, new customers and churn”, or pin charts from a [notebook](https://tini.so/docs/notebooks) with **Add to dashboard**. ## Working with widgets ### Chart widgets - **The title** is the query’s name unless you click it and type your own. A dashboard title doesn’t rename the query. - **The info icon** appears when the query has a description, and shows it. - **Chart settings** (the sliders icon, or the widget’s **⋯** menu) edits the chart right on the dashboard. - **Open query** goes to the query behind the chart. - **Remove from dashboard** takes the widget off this dashboard. The query and its chart stay, and so does the chart on any other dashboard. > **Note: A chart belongs to its query** > > Chart settings are saved on the query, so changing a chart on one dashboard changes it everywhere that query’s chart appears. For a different view of the same data, save the SQL as a second query. ### Text widgets Type straight into a text widget; it saves as you type. If a save fails, your draft is kept in the browser and offered back the next time you open the dashboard. On a shared dashboard’s public page, text is formatted as Markdown: `# Headings`, lists, `**bold**`, `*italic*` and links. ## Keeping numbers fresh A dashboard shows each query’s latest saved result, so it opens instantly and never slows down your database. That result is from the last time the query ran: when someone ran it, when the agent saved it, or when **Run all queries** was last used. To bring every chart up to date, open the **⋯** menu at the top of the dashboard and click **Run all queries**. Progress shows as each one runs. > **Important: No scheduled refresh yet** > > Dashboards don’t refresh on a schedule yet. For a Monday review, click **Run all queries** first. A chart that says *No result cached yet* needs its query run once. ## More - **Share** makes a public, read-only link. See [Share a dashboard](https://tini.so/docs/dashboards/sharing). - **Delete dashboard**, in the **⋯** menu, removes the dashboard only. Its queries and charts stay. - If the same dashboard is open in two tabs and one changes it, the other refreshes to the latest layout rather than overwriting it. - Big dashboards stay fast: each chart draws when you scroll near it, and very large results are sampled (see [Big results](https://tini.so/docs/charts#big-results)). ## A founder’s first dashboard Six charts cover a weekly review for most online businesses: 1. Revenue this month, as a Number with the change from last month 2. Revenue by week, as a Line 3. New customers by week, as a Column chart 4. Active customers, as a Number 5. Churn rate by month, as a Line 6. Revenue by plan or product, as a Bar chart Build them on certified [metrics](https://tini.so/docs/metrics) and they’ll agree with whatever the agent tells you. --- Previous: [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage.md) · Next: [Share a dashboard](https://tini.so/docs/dashboards/sharing.md) All docs: https://tini.so/llms.txt --- # Share a dashboard > Turn on a public link so anyone can view a dashboard, no account needed: what viewers see, what stays private, and how to stop sharing. Source: https://tini.so/docs/dashboards/sharing Everyone in your organization can already see every dashboard. To show one to someone outside it, an advisor, a partner or a contractor, turn on its **public link**. Anyone with the link can view the dashboard, read-only, without an account. ## Share a dashboard 1. **Open Share** On the dashboard, click **Share**. 2. **Switch on Public** Turn on **Public**. Access changes from *Only members of this organization* to *Anyone with the link can view*, and a **Public link** appears. 3. **Send the link** Click **Copy link**, or **Open public view** to see what others will see. The button on the dashboard now reads **Public**, so you can tell it’s shared. ## What viewers see, and what they don’t Viewers see the dashboard’s name and description, its layout and text widgets, and each chart drawn from its latest saved result. They never see: - the SQL behind any chart; - your data sources, or anything else in your organization; - who made the dashboard; - error messages from your database. The public page never runs a query: it shows the results already saved, from the last time each query ran. Run all queries on the dashboard before sending the link, so the numbers are current. See [Keeping numbers fresh](https://tini.so/docs/dashboards#freshness). > **Important: The link is the key** > > Anyone who has the link can view the dashboard, including anyone it gets forwarded to. Share it the way you’d share a document link, and only share dashboards whose numbers you’re happy for the recipient to see. ## Stop sharing Open **Share** and turn **Public** off. The link stops working straight away, for everyone. If you turn it on again later, you get a **new** link; the old one keeps not working. ## Link previews Paste a public link into Slack, X, Facebook or a messaging app, and it unfurls into a card with the dashboard’s name and description. Previews show only what the public page already shows. --- Previous: [Dashboards](https://tini.so/docs/dashboards.md) · Next: [Connect AI](https://tini.so/docs/connect-ai.md) All docs: https://tini.so/llms.txt --- # Connect AI > Use your Orcabase data from Claude and ChatGPT over MCP: what your assistant can do, what it can’t, and how it compares with the Data Agent. Source: https://tini.so/docs/connect-ai Already work in Claude or ChatGPT? Connect Orcabase, and your assistant can look up your data, run queries, use your certified metrics and build charts and dashboards in Orcabase, right from the conversation you’re already in. ## How it works AI assistants reach other apps through **MCP** (Model Context Protocol), an open standard for giving an assistant tools. Orcabase runs an MCP server at: `https://api.tini.so/api/mcp` Your assistant connects with an [API token](https://tini.so/docs/workspace/api-tokens) that belongs to one organization. The token decides whose data the assistant can see, so it can only ever reach that one organization, whatever it asks for. ## What your assistant can do - **Find its way around:** list your data sources, schemas and tables, read a table’s columns, and preview sample rows. - **Answer questions:** run SQL, re-run saved queries, and compute certified metrics by name, getting back the SQL that ran so answers can be checked. - **Build things:** save queries with charts, create dashboards and pin charts to them, create notebooks, and draft data models and metrics. The full list is in the [tools reference](https://tini.so/docs/connect-ai/tools). Things it saves show up in Orcabase like anything else, with the token’s name as their creator. ## What it can’t do - Edit or delete anything that already exists: queries, dashboards, models or metrics. - Certify metrics. The metrics it creates are drafts, until a person certifies them in Orcabase. - Add or change data sources, or upload data. Connections are set up by people, in Orcabase, because they involve passwords. - Reach another organization, or anything in Orcabase’s settings. > **Note** > > The SQL your assistant runs uses each data source’s own login, the same as SQL you run in Orcabase. Connect your databases with read-only users and nothing it runs can change your data. See [Security](https://tini.so/docs/security). ## The built-in agent or your assistant? | | Data Agent in Orcabase | Claude or ChatGPT | | --- | --- | --- | | Where you ask | Inside Orcabase, next to your dashboards | In the assistant you already use | | Answers | Insight, a chart you can change, and the steps | In the assistant’s own style | | AI costs | Orcabase AI credit, or your own gateway key | Your Claude or ChatGPT plan | | Conversations | Saved in Orcabase | Saved in the assistant | | Tools and guardrails | The same tools | The same tools, plus notebooks | Many teams use both: the agent for everyone in Orcabase, and Claude for whoever lives in it. ## Set it up - [Set up Claude and ChatGPT](https://tini.so/docs/connect-ai/setup): A token, then one step in your assistant. - [Tools reference](https://tini.so/docs/connect-ai/tools): Every tool, and what it does. --- Previous: [Share a dashboard](https://tini.so/docs/dashboards/sharing.md) · Next: [Set up Claude and ChatGPT](https://tini.so/docs/connect-ai/setup.md) All docs: https://tini.so/llms.txt --- # Set up Claude and ChatGPT > Create an API token, then add Orcabase to Claude Code, Claude Desktop, claude.ai or ChatGPT as an MCP connector. Commands and settings included. Source: https://tini.so/docs/connect-ai/setup Setting up takes two steps: create a token in Orcabase, then add Orcabase to your assistant. The app has the same instructions, filled in for your organization, under **Settings → MCP**. ## 1. Create a token 1. **Open API tokens** Go to **Settings → API Tokens → New token**. 2. **Name it and create it** Give it a name that says where it’s used, like “Claude, Jane’s laptop”, and click **Create token**. 3. **Copy it now** Click **Copy token**. It starts with `tnd_`, and it’s shown only this once: Orcabase keeps a scrambled version it can check, not the token itself. Lost it? Revoke it and create another. > **Important: Treat it like a password** > > Anyone with the token can query your organization’s data and create things in it. Keep it out of shared documents and code repositories. See [API tokens](https://tini.so/docs/workspace/api-tokens). ## 2a. Claude Code Run this once in a terminal, with your token in place of YOUR_TOKEN: ```bash claude mcp add --transport http orcabase-your-org \ https://api.tini.so/api/mcp \ --header "X-Api-Token: YOUR_TOKEN" ``` Check it with `claude mcp list`, then just ask: “What data sources do we have?” or “Chart daily signups for the last 30 days.” Replace `orcabase-your-org` with your organization’s name, as below. ## 2b. Claude Desktop and claude.ai 1. **Add a custom connector** Go to **Settings → Connectors → Add custom connector** and paste `https://api.tini.so/api/mcp` as the URL. 2. **Choose “No sign-in”** Under **Authentication**, pick **No sign-in**, the option for servers that use an API key. Claude suggests signing in with OAuth first; Orcabase doesn’t use OAuth, so skip that. 3. **Add the token as a header** Still on that screen, add a **Request header** named `x-api-token` with your token as its value, mark it required, and click **Add**. ## 2c. ChatGPT Whether ChatGPT can add a connector that uses a header token depends on your plan and ChatGPT’s current rollout. Where it can’t, the same endpoint and token work from a Custom GPT action, or from OpenAI’s Responses API with its built-in MCP support: ```text URL: https://api.tini.so/api/mcp Header: X-Api-Token: YOUR_TOKEN ``` ## More than one organization A token only ever reaches one organization. If you work in several, create a token in each and add one connection per organization, named after it, so the second doesn’t replace the first: ```bash claude mcp add --transport http orcabase-acme https://api.tini.so/api/mcp \ --header "X-Api-Token: ACME_TOKEN" claude mcp add --transport http orcabase-globex https://api.tini.so/api/mcp \ --header "X-Api-Token: GLOBEX_TOKEN" ``` Claude Code keeps every connection open, so you can say “using orcabase-acme…” and then “now the same for orcabase-globex” in one conversation. ### If it doesn’t connect - **401 or “unauthorized”:** the token is wrong, revoked, or missing its header. Check the header name (`X-Api-Token`) and that the whole token was pasted. - **Claude asks for an OAuth client ID:** go back and pick **No sign-in** under Authentication. - **The assistant can’t find a table:** the data source has to exist in Orcabase first. Tokens can’t add data sources. --- Previous: [Connect AI](https://tini.so/docs/connect-ai.md) · Next: [Tools reference](https://tini.so/docs/connect-ai/tools.md) All docs: https://tini.so/llms.txt --- # Tools reference > Every MCP tool your AI assistant gets from Orcabase, grouped by what it does, plus what’s deliberately left out: no edits, deletes or settings. Source: https://tini.so/docs/connect-ai/tools These are the tools Orcabase gives an AI assistant over MCP. The built-in [Data Agent](https://tini.so/docs/agent) uses the same ones, except the two notebook tools, plus one of its own for drawing charts in the chat. Every tool acts on the organization the token belongs to. ## Discover | Tool | What it does | | --- | --- | | `list_data_sources` | Lists the data sources the assistant can query: name, engine (Postgres, BigQuery or DuckDB) and kind. | | `list_schemas` | Lists the schemas (BigQuery datasets) in a data source. | | `list_tables` | Lists the tables and views in a schema. | | `describe_table` | A table’s columns and types, so SQL is written against the real schema instead of guesses. | | `preview_table` | A handful of sample rows, to see real values, formats and codes. | ## Query | Tool | What it does | | --- | --- | | `run_query` | Runs SQL against a data source and returns the result (up to 5,000 rows). Saves nothing. | | `list_queries` | Lists saved queries, so existing work is reused rather than rewritten. | | `run_saved_query` | Re-runs a saved query and saves its new result, which is what dashboards show. | ## Metrics and data models | Tool | What it does | | --- | --- | | `list_metrics` | Your metrics, certified first, with their descriptions and status. | | `describe_metric` | One metric in words, and every field it can be split or filtered by, with time grains. | | `query_metrics` | Computes metrics from their definitions, grouped and filtered, and returns the rows plus the SQL that ran. | | `list_data_models` | Your data models, with their dimensions, measures and joins. | | `describe_data_model` | One data model in full, including the SQL behind each dimension and measure. | | `scaffold_data_model` | Drafts a data model from a table’s columns. Saves nothing. | | `create_data_model` | Creates a new data model. Fails if the name is taken, so it never overwrites one. | | `create_metric` | Creates a new metric, always as a draft for a person to certify. | > **Tip: Metrics first** > > The tool descriptions tell assistants to reach for `query_metrics` whenever a certified metric fits the question, and to write SQL only when none does. That’s what keeps an assistant’s numbers matching your dashboards. ## Build | Tool | What it does | | --- | --- | | `save_query` | Saves SQL, or a metric query, as a query in Orcabase, optionally with its chart. | | `list_dashboards` | Lists dashboards. | | `get_dashboard` | A dashboard and the charts already on it. | | `create_dashboard` | Creates an empty dashboard. | | `add_widget` | Pins a saved query’s chart to a dashboard. Without a position, it takes the first free spot. | | `create_notebook` | Creates an empty notebook. Not available to the built-in agent. | | `add_notebook_cell` | Adds a SQL cell (saving a new query) or a text cell to a notebook. Not available to the built-in agent. | ## Deliberately left out There are no tools to edit or delete anything, to certify or deprecate metrics, to add data sources or upload data, or to manage members, tokens and settings. Those stay with people, in Orcabase. See [What it can’t do](https://tini.so/docs/connect-ai#guardrails). --- Previous: [Set up Claude and ChatGPT](https://tini.so/docs/connect-ai/setup.md) · Next: [Members and roles](https://tini.so/docs/workspace/members.md) All docs: https://tini.so/llms.txt --- # Members and roles > Invite teammates with a link, choose who’s an admin, and see what each role can do. Members sign in with Google, in one or more organizations. Source: https://tini.so/docs/workspace/members Everyone who uses Orcabase is a **member** of an organization. Members sign in with their Google account, and each has one of two roles: **Member** or **Admin**. Manage them under **Settings → Members**. (The gear at the bottom of the sidebar opens Settings.) ## Invite someone 1. **Fill in the invite** Go to **Settings → Members → Invite member**. Enter their **Email** (the one on their Google account), their name if you like, and a **Role**. 2. **Send the link yourself** Click **Invite**, then copy the invite link and send it to them however you like. Orcabase doesn’t send emails. You can copy the link again later from the members list with **Copy invite**. 3. **They accept** They open the link and continue with Google. It can be a different Google account from the email you invited: the first account to accept the link becomes the member, and the link can’t be used by anyone else after that. > **Tip: Invite as Member by default** > > Most people only need the Member role: it covers everything except a few organization-wide settings (below). Make someone an Admin when they’ll set up the agent, syncs or hosted servers. ## Roles | | Member | Admin | | --- | --- | --- | | Explore data, run SQL, and ask the agent | Yes | Yes | | Create and edit queries, notebooks and dashboards; share dashboards | Yes | Yes | | Create, edit and certify data models and metrics | Yes | Yes | | Add and edit data sources | Yes | Yes | | Create and revoke API tokens | Yes | Yes | | See Sync data and each source’s status | Yes | Yes | | Add, change, run and remove synced sources (built-in and Fivetran) | | Yes | | Set up the agent: provider, key, models, step limit, usage | | Yes | | See and manage hosted Postgres servers | | Yes | | Rename the organization and change its URL | | Yes | Everything in an organization is shared with all its members: there are no private dashboards or queries. The exceptions are agent chats, which only their author sees. ## Change a role or remove someone - Change a member’s role with the **Role** picker next to their name. - **Remove member** takes them out of the organization. They lose access within 15 minutes, and anything they made stays. ## Belonging to several organizations One Google account can be a member of several organizations, with a different role in each: an agency working for several clients, say, or a founder with two companies. After signing in you land on the **Organizations** page; pick one to work in. Click the Orcabase logo at any time to come back and switch. See [Organization and account](https://tini.so/docs/workspace/settings). --- Previous: [Tools reference](https://tini.so/docs/connect-ai/tools.md) · Next: [API tokens](https://tini.so/docs/workspace/api-tokens.md) All docs: https://tini.so/llms.txt --- # API tokens > Create, use and revoke the API tokens that let AI assistants reach your data. Each token belongs to one organization and is shown only once. Source: https://tini.so/docs/workspace/api-tokens An **API token** lets an AI assistant, like Claude or ChatGPT, reach your organization’s data through Orcabase’s [MCP server](https://tini.so/docs/connect-ai). Each token belongs to one organization and can only ever see that organization. ## Create a token 1. Go to **Settings → API Tokens → New token**. 2. Name it after where it’ll be used, like “Claude, Jane’s laptop”, and click **Create token**. 3. Click **Copy token** and paste it into your assistant. See [Set up Claude and ChatGPT](https://tini.so/docs/connect-ai/setup). > **Important: You’ll only see it once** > > Orcabase stores a scrambled version of the token that it can check, not the token itself, so it can’t show it again. If you lose it, revoke it and make a new one. ## The token list | Column | Shows | | --- | --- | | Name | The name you gave it. | | Status | Active, or Revoked. | | Created | When it was made. | | Last used | When an assistant last used it, or Never. A quick way to spot tokens nobody needs. | ## Revoke a token Click **Revoke token** next to it. It stops working on the very next request, with nothing to wait for. Things created with it stay. ## Good habits - One token per person and per device, so you can revoke one without breaking the others. - Never put a token in a shared document, a chat message or a code repository. - Revoke tokens that show as unused for a long time, and when someone leaves the team. - Things a token creates show `mcp:` and the token’s name as their creator, so a clear name tells you where they came from. --- Previous: [Members and roles](https://tini.so/docs/workspace/members.md) · Next: [Organization and account](https://tini.so/docs/workspace/settings.md) All docs: https://tini.so/llms.txt --- # Organization and account > Rename your organization, change its URL, set your name, switch between organizations, pick light or dark mode, and sign out of Orcabase. Source: https://tini.so/docs/workspace/settings Two kinds of settings: your organization’s, shared by everyone in it, and your own account’s. Organization settings open from the gear at the bottom of the sidebar; your account is in the menu under your name, top right. ## Organization settings - **Organization** “Admins”: the organization’s **Name**, and its **URL slug**, the part of the address after `app.orcabase.co/`. Slugs use lowercase letters, numbers and single hyphens. - **Members**: who’s in the organization and their roles. See [Members and roles](https://tini.so/docs/workspace/members). - **API Tokens**: tokens for AI assistants. See [API tokens](https://tini.so/docs/workspace/api-tokens). - **MCP**: step-by-step setup for Claude and ChatGPT, filled in for your organization. See [Set up Claude and ChatGPT](https://tini.so/docs/connect-ai/setup). - **Agent** “Admins”: the Data Agent’s provider, models, step limit and usage. See [Set up the agent](https://tini.so/docs/agent/setup). > **Important: Changing the URL slug** > > Links and bookmarks with the old slug stop working, including links you’ve shared with teammates. Public dashboard links aren’t affected: they don’t include the slug. ## Your account Open the menu under your name and choose **Account settings**. Your **Name** is shown across Orcabase in place of your email. Your email comes from your Google account and can’t be changed here. ## Switching organizations Click the Orcabase logo, top left, to go back to the **Organizations** page and pick another organization. Each has its own data, settings and role for you. ## Light and dark The theme button at the bottom of the page switches between light, dark and your system’s setting. It’s remembered in your browser. ## Signing out Choose **Logout** in the menu under your name. Orcabase keeps you signed in while you use it, and signs you out after 7 days away. See [Security](https://tini.so/docs/security#sessions). Your organization’s Home page lives at `app.orcabase.co/your-slug`, so a bookmark of it takes you straight in. --- Previous: [API tokens](https://tini.so/docs/workspace/api-tokens.md) · Next: [Security](https://tini.so/docs/security.md) All docs: https://tini.so/llms.txt --- # Security > How Orcabase keeps your data safe: read-only logins, encrypted credentials, organizations kept apart, AI guardrails and limits on every query. Source: https://tini.so/docs/security Orcabase sits between your data and the people and AI models asking about it, so it’s built to read, not change; to keep secrets secret; and to keep every organization’s data apart. Here’s how, in plain words. ## Read-only access comes from the login Orcabase doesn’t try to spot dangerous SQL and block it. Instead, it relies on something that can’t be talked around: the database login it uses. A login that can only read can’t change anything, whoever writes the query and however it’s worded. | Data source | What Orcabase connects as | | --- | --- | | Hosted Postgres server | A built-in read-only user: it can read every table and nothing else, and its queries stop after 30 seconds. | | Your own Postgres | The user you enter. We recommend a [read-only user](https://tini.so/docs/data/postgresql#read-only-user). | | BigQuery | The service account you enter. With BigQuery Data Viewer and Job User only, it can read and query but not change tables. | | DuckDB warehouse | Full access: it’s your workspace, and SQL can create and change tables in it. Syncs rebuild their own tables. | | Sync sources | Read only. Syncs copy from Google Sheets, MySQL and Fivetran sources and never write back. | > **Tip** > > With read-only logins on your own databases, nothing in Orcabase can change your data: not a teammate, not the Data Agent, and not an AI assistant connected over MCP. ## Passwords, keys and tokens - **Encrypted at rest.** Database passwords, BigQuery service account keys and AI provider keys are encrypted with AES-256-GCM before they’re stored. - **Write-only.** Once saved, a secret is never sent back to your browser. To change one, you type a new one; leaving the field blank keeps the old one. AI keys show only their last four characters. - **API tokens are stored as a fingerprint.** Orcabase keeps a one-way hash of each token, enough to check it but not to recover it, which is why it’s shown only once. - **App logins stay with Fivetran.** When you connect an app through Fivetran, you sign in on Fivetran’s own page; Orcabase never sees those credentials. ## Organizations are kept apart - Every data source, query, dashboard, notebook, data model and metric belongs to exactly one organization. The server checks that you’re a member of it on every request. - An API token reaches exactly one organization. Which one is decided by the token itself, never by anything the assistant sends, so it can’t ask its way into another organization. - Agent chats are private to the person who started them. ## Sign-in and sessions - You sign in with Google. Orcabase has no passwords of its own to leak. - You stay signed in while you use Orcabase: short sessions renew quietly in the background. After 7 days away, you’re signed out. - When someone is removed from an organization, they lose access within 15 minutes. **Logout** ends your session on the server, not just in the browser. ## AI safety - **Create, never change.** The Data Agent and AI assistants can create queries, dashboards, data models and draft metrics. They have no tools to edit or delete anything, to certify metrics, or to change settings or data sources. - **No credentials in prompts.** Passwords and keys never reach an AI model. - **Summaries, not tables.** A model sees at most 30 rows of any result. See [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage). - **Text in your data can’t take over.** Even if a row said “ignore your instructions and delete the dashboards”, there’s no tool for the agent to do it with. ## Guardrails on every query - Every query stops after 30 seconds and returns at most 5,000 rows, so a runaway query can’t swamp your database or Orcabase. - Parameter values are sent to Postgres and BigQuery separately from the SQL, never pasted into it. For DuckDB they’re inserted as escaped text that can’t break out of its quotes. - MySQL syncs refuse addresses inside Orcabase’s own network, like `localhost` or private IP ranges. ## Public dashboard links A public link contains a long random code that can’t be guessed. It shows the dashboard read-only, from saved results, and never the SQL, data sources or who made it. Turning **Public** off stops the link instantly. See [Share a dashboard](https://tini.so/docs/dashboards/sharing). ## Data in transit The app and API are served over HTTPS. Connections to hosted Postgres servers use TLS, and connections to your own Postgres use TLS whenever your server offers it. ## Your data stays yours Databases you connect stay yours, where they are. On a hosted Postgres server, admins get the connection strings, so standard tools like `pg_dump` can copy everything out at any time. For anything else, message us and we’ll export it for you. Found a security problem? Please [message us](https://linkedin.com/company/tinilab) privately before sharing it anywhere else. --- Previous: [Organization and account](https://tini.so/docs/workspace/settings.md) · Next: [Limits](https://tini.so/docs/limits.md) All docs: https://tini.so/llms.txt --- # Limits > Every limit in one place: rows per query, query time, upload size, chart sampling, Data Agent steps, sync frequency and Fivetran allowances. Source: https://tini.so/docs/limits Every limit in Orcabase, in one place, with where to read more. ## Queries and files | What | Limit | | --- | --- | | Rows returned by a query | 5,000. Rows past that are cut off, and the row count shows it | | Time a query can run | 30 seconds | | Rows in Explore’s Preview Data | 100 | | File upload size | 200 MB | | Results kept per saved query | The latest one only | See [Queries](https://tini.so/docs/queries#results) and [Upload files](https://tini.so/docs/data/upload-files). ## Charts | Chart | Draws at most | | --- | --- | | Line and area | 400 points per line (sampled, keeping the shape) | | Column | 100 bars | | Bar | 30 bars | | Scatter | 500 points | | Heatmap | 60 × 40 cells | | Table on a dashboard | 200 rows | | Series colors | 8; the rest are grouped as “Other” | See [Big results](https://tini.so/docs/charts#big-results). ## Data Agent | What | Limit | | --- | --- | | Steps per question | 30 by default; an admin can set 5 to 100. At the limit, the agent asks before going on | | Rows of a result the AI model sees | 30, and 16,000 characters | | Rows behind a chart in a chat | 1,000 | | Messages in one chat | 400. Start a new chat after that | | Questions answering at once, per chat | 1 | | Models an organization can offer | A default, plus up to 8 more | | Orcabase AI credit | Daily, weekly and monthly limits, set by your plan | See [Data Agent](https://tini.so/docs/agent) and [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage). ## Syncs | What | Limit | | --- | --- | | Built-in sync frequency | Every 15 minutes to once a day; 6 hours by default | | Fivetran monthly active rows | 500,000 a month, standard | | Fivetran sources | 5, standard | | Fivetran sync frequency | Every 6 hours at most, standard | Fivetran limits can differ by plan. See [Your monthly allowance](https://tini.so/docs/data/fivetran#allowance). ## Sign-in | What | Limit | | --- | --- | | Staying signed in | Renewed while you use Orcabase; signed out after 7 days away | | Access after being removed | Ends within 15 minutes | --- Previous: [Security](https://tini.so/docs/security.md) · Next: [Troubleshooting](https://tini.so/docs/troubleshooting.md) All docs: https://tini.so/llms.txt --- # Troubleshooting > Fixes for the errors people run into most: signing in, connecting data sources, queries and dashboards, metrics, the agent, syncs and MCP. Source: https://tini.so/docs/troubleshooting The messages people run into most, what they mean, and what to do. Search this page for a word from the error (Ctrl F, or ⌘ F on a Mac). ## Signing in | You see | What to do | | --- | --- | | “… isn’t invited to any organization — ask them to invite you first” | You signed in with a Google account that has no invite. Sign in with the account the invite was sent to, open your invite link and continue with this account there, or ask an admin to invite this email. | | “No organization found at …” | The address has an old or wrong organization name in it. Click the Orcabase logo and pick your organization. | | You were signed out | Orcabase signs you out after 7 days away, and within 15 minutes of being removed from an organization. Sign in again, or ask an admin. | ## Data sources | You see | What to do | | --- | --- | | Test connection fails | See the error table on [PostgreSQL](https://tini.so/docs/data/postgresql#troubleshooting) or [BigQuery](https://tini.so/docs/data/bigquery#troubleshooting). Most often the database doesn’t accept connections from the internet, or the login is wrong. | | “No Postgres servers are assigned to this organization yet” | Only admins can pick hosted Postgres servers. Ask an admin to add the data source, or message us if you don’t have a server yet. | | “No DuckDB projects exist yet” | DuckDB warehouses are added by the Orcabase team. Message us to set one up. | | An upload fails with “permission denied” | The data source’s login can’t create tables. Upload into your DuckDB warehouse instead. See [Uploading into Postgres](https://tini.so/docs/data/upload-files#postgres). | | An upload fails with “already exists” | A table with that name is already there. Pick a new table name. | | An upload fails as too large | Files can be up to 200 MB. Split the file, or save it as Parquet, which is much smaller. | ## Queries and dashboards | You see | What to do | | --- | --- | | The query times out | Queries stop after 30 seconds. Filter to a shorter period, add up in SQL (GROUP BY) instead of returning raw rows, or ask whoever runs the database about indexes. | | Only 5,000 rows come back | That’s the most a query returns. Add up or filter in SQL so the answer fits. | | A dashboard shows old numbers | Dashboards show each query’s last saved result and don’t refresh on a schedule yet. Use **Run all queries** in the dashboard’s ⋯ menu. | | “No result cached yet — run the underlying query” | The query behind the chart has never run. Open it from the widget’s menu and run it. | | A chart changed on a dashboard you didn’t touch | Chart settings belong to the query, so an edit on one dashboard shows everywhere that query’s chart appears. | | A chart is wrong after Run all queries | Its query has parameters, and Run all queries runs them empty. Use a query without parameters for dashboard charts. | ## Metrics and data models | You see | What to do | | --- | --- | | “… crosses a one-to-many join and would double-count” | The split you asked for would count rows more than once. Define the metric on the other model, as the message suggests. See [Correct or loud](https://tini.so/docs/semantic-layer#correct-or-loud). | | A Broken badge on a data model | Its table changed, for example a column was renamed. Click the badge to see which dimension or measure fails, and update its expression. | | “… is still used by …” when deleting | Something depends on it; the message lists what. Change those first, or deprecate instead of deleting. | | A certified metric is back to Draft | Its formula changed. Check it and certify it again. | ## Data Agent | You see | What to do | | --- | --- | | “Ask an organization admin to set it up in Settings → Agent” | The agent isn’t set up for your organization yet. An admin can do it in a few minutes: see [Set up the agent](https://tini.so/docs/agent/setup). | | “This is taking a while. Keep going?” | The question used its allowance of steps. Click Continue to carry on, or ask something narrower. | | “This chat is still answering the last question” | A chat answers one question at a time. Wait for it, or start a new chat. | | “Your organization has used … Orcabase AI credit” | A daily, weekly or monthly limit is used up. The message says when it resets. An admin can switch to your own key in the meantime. | | Test and save fails | The key is wrong, has no credit left, or can’t use that model. Check it in your OpenRouter or Vercel account. | ## Syncs | You see | What to do | | --- | --- | | “can’t open this spreadsheet — share it with …” | Share the Google Sheet with the address shown, as a Viewer. | | “spreadsheet not found — check the link” | Copy the link again from the sheet’s address bar. | | “… is a private address” | Orcabase can’t reach private network addresses. Use the database’s public address. | | “… can’t contain spaces or quotes” | MySQL connection details can’t include spaces or quote marks. Change the password to one without them. | | Needs reconnecting | Orcabase can’t sign in to the source any more. Update the connection details, or click Reconnect for a Fivetran source. | | Paused: limit reached | Your organization used this month’s Fivetran allowance. See [Your monthly allowance](https://tini.so/docs/data/fivetran#allowance). | ## Claude and ChatGPT | You see | What to do | | --- | --- | | 401 or “unauthorized” | The token is wrong or revoked, or the header isn’t named X-Api-Token. Create a new token if in doubt. | | Claude asks for an OAuth client ID | Pick No sign-in under Authentication, then add the token as a request header. | | The assistant can’t find your data | Make sure the token belongs to the right organization, and that the data source exists in Orcabase. | Still stuck? [Message us](https://linkedin.com/company/tinilab) with what you did and the exact message you saw. --- Previous: [Limits](https://tini.so/docs/limits.md) · Next: [FAQ](https://tini.so/docs/faq.md) All docs: https://tini.so/llms.txt --- # FAQ > Short answers to common questions about Orcabase: what it is, connecting and exporting your data, the AI agent, sharing, teams and pricing. Source: https://tini.so/docs/faq ## The basics ### What is Orcabase? An AI-native data platform for founders: all your business data in one place, with an AI agent that understands it. See [How Orcabase works](https://tini.so/docs/how-it-works). ### Do I need to know SQL? No. Ask the Data Agent in plain words, build dashboards by pointing and clicking, and explore metrics without code. SQL is there for anyone who wants it. ### How do I get access? By invitation. When your company joins, we set up your organization and send you an invite link; after that, you invite your team. See [Quickstart](https://tini.so/docs/quickstart). ### What does it cost? Plans are priced by team size, with every feature on every plan. See [Pricing](https://tini.so/pricing). ## Your data ### Which data can I connect? PostgreSQL and BigQuery directly; Google Sheets and MySQL through built-in syncs; hundreds of apps through Fivetran; and CSV, Parquet or JSON files. See [Connect your data](https://tini.so/docs/data). ### Does Orcabase copy my database? No. Connected databases are queried live, where they are. Orcabase keeps only the latest result of each saved query, up to 5,000 rows, so dashboards open quickly. Synced and uploaded data is copied, into a warehouse Orcabase hosts for you. ### Can Orcabase change my data? Not if you connect with a read-only login, which we recommend. Orcabase then can’t change anything, whoever writes the query. See [Security](https://tini.so/docs/security). ### I don’t have a database. Can I still use Orcabase? Yes. Orcabase can host one for you, and you can fill it with synced spreadsheets and uploaded files. See [Hosted by Orcabase](https://tini.so/docs/data/hosted). ### Can I get my data out? Yes. Connected databases never leave your hands. Hosted Postgres servers come with connection strings, so standard tools can copy everything out, and we’ll export anything else on request. ## The agent and AI ### Which AI models does the agent use? Your admin chooses: models from Orcabase AI, or hundreds through your own OpenRouter or Vercel AI Gateway key. See [Set up the agent](https://tini.so/docs/agent/setup). ### What does the AI provider see? Your question, how your data is organized, and small samples of results (never more than 30 rows). Never passwords or keys. See [AI privacy and usage](https://tini.so/docs/agent/privacy-and-usage). ### Can the agent break anything? It can only create things: queries, dashboards, data models and draft metrics. It can’t edit or delete anything, and only a person can certify a metric. ### Why doesn’t the agent’s answer match my spreadsheet? Usually because the two define the number differently. Define it once as a certified [metric](https://tini.so/docs/metrics), and the agent will use that definition, and say so. ### Can I use Orcabase from Claude or ChatGPT? Yes, through MCP, with the same tools and guardrails as the built-in agent. See [Connect AI](https://tini.so/docs/connect-ai). ## Sharing and teams ### Can people outside my company see a dashboard? Yes, with a public link: read-only, no account needed, and you can turn it off anytime. See [Share a dashboard](https://tini.so/docs/dashboards/sharing). ### Can I keep a dashboard private from some teammates? Not yet. Everything in an organization is visible to all its members. Agent chats are the exception: they’re private to their author. ### Do dashboards refresh automatically? Not yet. Dashboards show each query’s last saved result; use Run all queries to update them. --- Previous: [Troubleshooting](https://tini.so/docs/troubleshooting.md) All docs: https://tini.so/llms.txt