Skip to main content
The Hasura destination inserts uploaded spreadsheet data from CSVbox into a table exposed by your Hasura GraphQL API. Rows are validated, batched, and sent as GraphQL mutations, with optional upsert support.

​
Before you start

  • A Hasura project with a GraphQL endpoint URL, for example https://your-project.hasura.app/v1/graphql
  • The project’s admin secret
  • A table already tracked in Hasura, with insert permissions available to the admin role
  • An endpoint reachable from the public internet
A sheet can have only one destination at a time. Selecting Hasura replaces whatever the sheet was writing to before.

​
Setup

In your Sheet Settings, open the Destination tab and choose Hasura. Then work through the fields in order. The column mapping unlocks only after the connection test passes.
1

Enter your GraphQL endpoint

Paste the full endpoint URL, including the /v1/graphql path.
You’ll find this on the Hasura Cloud project page, or it’s the endpoint your own instance serves.
2

Enter your admin secret

Provide the value of your project’s x-hasura-admin-secret. In Hasura Cloud, it lives under Project → Env Vars → HASURA_GRAPHQL_ADMIN_SECRET.
CSVbox stores credentials in encrypted form and uses them only to insert rows into the table you specify.
3

Set the target table

Enter the table you want rows inserted into, for example users. Use the name exactly as Hasura exposes it in your GraphQL schema.If the table is tracked under a non-public schema or carries a custom GraphQL name, use that name: the one that appears as insert_<name> in your API.
4

Test the connection

Click Test Connection. CSVbox introspects your schema to confirm that the endpoint, admin secret, and table all check out, and loads the table’s column list for mapping.A green check means everything is ready. If it fails, see Troubleshooting.
5

Map columns to table fields

Click Map Columns. For each column in your importer, including any virtual columns, pick the Hasura column it should be written to. Each target’s data type is shown next to its name, so you can confirm the destination is the one you meant.Leave a row set to (empty) to skip that column; it isn’t sent.
6

Map custom attributes (optional)

In the same window, the Custom Attributes table writes values you pass into the importer at runtime into columns on the target table. This is how every imported row gets tagged with the tenant, account, or user it belongs to.user_id is available by default, and you can define up to five attributes in total. Values come from the user object you set on the importer:
Map team_id to a team_id column, and every row from that import carries it.
7

Save

Save the mapping, then save the sheet. The next file submitted through this importer writes to Hasura.

​
Insert vs. upsert

By default, every import performs a plain insert: each row becomes a new row in the table. To upsert instead, updating existing rows rather than duplicating them, fill in the two optional fields: Leaving Upsert Constraint blank disables upsert entirely; the update-columns value is then ignored.
Be careful with large files. Plain inserts are not idempotent: if an import is retried after a partial failure, rows already written by a completed batch can be inserted a second time. An upsert on a unique constraint makes retries safe, which is why it’s the better choice for big files, not just for deduplication.

​
Data flow

Once setup is complete, every submitted file is processed without further intervention. Each import ends in one of three states, visible on the Imports page in your dashboard:

​
How values are converted

Spreadsheet cells are text. Before sending a batch, CSVbox converts each value to the JSON type your column expects, based on the schema read during Test Connection.
Because date, timestamp, UUID, and JSON values pass through as strings, the values in your file need to be in a form Postgres accepts, for instance 2026-03-14 or 2026-03-14T09:30:00Z for timestamps. Use validation rules and data transform functions to normalize them before they’re sent.

​
Environment variables

The endpoint, admin secret, table name, and upsert settings all accept environment variables. Wrap the variable name in double curly braces, and CSVbox substitutes it at import time:
Pass the value when you create the importer:
One importer can then write to a different Hasura project, table, or upsert constraint per customer or per environment.

​
Troubleshooting

​
Notes & limits

  • Only insertable scalar columns appear in the mapping list. Columns backed by Postgres enums, arrays, or Hasura relationships aren’t offered as targets, and nested or related inserts aren’t supported.
  • Authentication uses the admin secret only. JWT and webhook auth modes aren’t supported for this destination.
  • Column names are case-sensitive and must match your Hasura schema exactly.
  • Generated columns and columns with database defaults can be left unmapped; Hasura and Postgres fill them in.
  • Hasura can return errors inside an otherwise successful HTTP response. CSVbox inspects every response body, so a rejected batch is always reported as an import error rather than counted as a silent success.
  • This destination composes with the rest of CSVbox: validation rules, virtual columns, data transform functions, and AI transforms all apply before rows are sent.