Skip to content
  • docs
  • data model
  • data builder
  • fields
  • jsonb

JSONB Field

The JSONB field (labeled as jsonb in the interface) is used to store unstructured or semi-structured data sets, such as Objects {...} or Arrays [...].

Unlike a standard Text field, this field uses the JSONB (Binary JSON) format. This means the database verifies that the input is valid JSON before saving it, and it stores the data in a decomposed binary format that allows for efficient indexing and querying of specific keys within the structure.

Configuration Properties

Section titled “Configuration Properties”

When configuring a JSON field in the right-hand sidebar, the following settings are available:

  • Name: The unique system identifier for the field (e.g., metadata, settings, api_response).
  • Default Value: A valid JSON object or array to be assigned if no data is provided (e.g., {"theme": "dark"} or []).
  • Description: An optional text box to describe the schema or purpose of the JSON data.
  • Mandatory: If enabled, the record cannot be saved unless valid JSON data is provided.
  • Unique: If enabled, ensures that no two records have the exact same JSON structure and content.
    • Note: This enforces exact binary equality, meaning {"a": 1, "b": 2} would likely be considered equal to {"b": 2, "a": 1} depending on database normalization, but distinct from {"a": 1}.

Tip: Why JSONB? We use the JSONB data type instead of standard JSON. While slightly slower to write, JSONB is significantly faster to query. It supports indexing (GIN), which allows you to perform high-performance searches and filtering directly on keys and values within the JSON object (e.g., finding all users where attributes->'color' is “blue”).

Common Use Cases

Section titled “Common Use Cases”
  • Configuration/Settings: Storing user preferences that might change often without needing new database columns (e.g., {"notifications": true, "theme": "dark"}).
  • External API Data: Storing raw responses from third-party integrations (e.g., Stripe webhooks or logging payloads).
  • Dynamic Attributes: Product details that vary wildly between categories (e.g., a T-shirt has size and color, but a Laptop has ram and cpu).
  • Lists: Storing simple arrays of strings or numbers (e.g., ["tag1", "tag2", "tag3"]).