Individual data tables within Workbooks that organize and structure imported data
access
you can control Sheet-level access for users.
Access Level | Description |
---|---|
"*" (default) | A user can use all access actions to this Sheet |
"add" | A user can add a record(s) to the Sheet |
"delete" | A user can delete record(s) from the Sheet |
"edit" | A user can edit records (field values) in the Sheet |
"import" | A user can import CSVs to this Sheet |
<empty> | If no parameters are specified in the access array, sheet-level readOnly access will be applied |
"*"
access control, users will gain new functionalities as we expand
access controls. Use an exhaustive list today to block future functionality from
being added automatically.Property | Type | Required | Description |
---|---|---|---|
name | string | ✓ | Unique identifier for the constraint |
type | string | ✓ | Must be "unique" for composite uniqueness constraints |
fields | string[] | ✓ | Array of field names that must be unique together |
requiredFields | string[] | Subset of fields that when empty, disables constraint validation | |
strategy | string | ✓ | Either "concat" or "hash" - determines how uniqueness is calculated |
Strategy | Description | Best Used When |
---|---|---|
concat | Concatenates field values to determine uniqueness | Simple field types, debugging needed, performance critical |
hash | Uses SHA1 hash of combined field values for uniqueness | Complex values, collision avoidance, data privacy |
strategy
property determines how uniqueness is calculated. You can choose to simply concatenate the field values as a single string or use a SHA1 hash function to create a unique identifier. Consider the following when choosing a strategy:
Use concat
when:
hash
when:
concat
strategy would consider the following records to be duplicates:
concat
strategy:
hash
strategy would prevent this, because the hash function creates a unique identifier based on each field’s invividual value rather than a simple concatenation.
hash
strategy:
requiredFields
property enables conditional uniqueness validation. When any field specified in requiredFields
is empty (null, undefined, or empty string), the entire constraint is ignored for that record.
Use Cases:
requiredFields
should contain only fields that exist in the fields
arraynull
, undefined
, or empty strings (""
)requiredFields
is omitted, the constraint always appliesemail
is provided:
Company | Validation Result | Reason | |
---|---|---|---|
"john@acme.com" | "Acme Corp" | ✅ Enforced | Email provided |
"jane@acme.com" | "Acme Corp" | ❌ Duplicate | Same email+company combination |
"" | "Acme Corp" | ⏭️ Ignored | Email empty (required field) |
null | "Beta Inc" | ⏭️ Ignored | Email null (required field) |
"bob@beta.com" | "" | ✅ Enforced | Email provided, company can be empty |
requiredFields
:
All records would be validated, potentially causing errors during partial data imports.
orderId
and productId
have non-empty values. If either is empty, the entire constraint is ignored.
treatments
parameter which takes an array of treatments for your Sheet. Treatments can be used to categorize your Sheet and control its behavior. Certain treatments will cause your Sheet to look or behave differently.
"ENUM_REFERENCE"
will mark it as reference data for other sheets. Reference sheets are currently hidden from view, allowing you to generate a number of reference values without adding visual distraction for the user.
enum
field."ENUM_REFERENCE"
is the only treatment that changes the behavior of your Sheet.
Option | Type | Required | Description |
---|---|---|---|
name | string | ✓ | The name of your Sheet as it will appear to your end users |
description | string | A sentence or two describing the purpose of your Sheet | |
slug | string | A unique identifier for your Sheet. Used to reference your Sheet in code, for example in a Record Hook | |
readonly | boolean | A boolean specifying whether or not this sheet is read only. Read only sheets are not editable by end users | |
allowAdditionalFields | boolean | When set to true , your Sheet will accept additional fields beyond what you specify in its configuration. These additional fields can be added via API, or by end users during the file import process | |
access | array | An array specifying the access controls for this Sheet. Valid values: "*" , "add" , "edit" , "delete" , "import" . Read more about access controls | |
fields | array | ✓ | This is where you define your Sheet’s data schema. The collection of fields in your Sheet determines the shape of data you wish to accept (minimum: 1, maximum: 1000) |
actions | array | An array of actions that end users can perform on this Sheet. Read more about actions | |
constraints | array | An array of sheet-level validation constraints that apply across multiple fields or entire sheets. Read more about sheet constraints | |
metadata | object | Use metadata to store any extra contextual information about your Sheet. Must be valid JSON | |
mappingConfidenceThreshold | number | Configure the minimum required confidence for mapping jobs targeting that sheet (default: 0.5, range: 0-1) |