Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Structures

Structures in Kinesis API define individual fields within collections. Unlike traditional database systems where you might define an entire schema at once, Kinesis API uses structures to represent each individual field in your data model. This granular approach offers greater flexibility and reusability.

Understanding Structures

Each structure represents a single field that can be used within collections. Key characteristics of structures include:

  • Each structure defines exactly one field with its data type and validation rules
  • Structures can be reused across multiple collections
  • They establish specific validation rules for individual data elements
  • They support both simple and complex data types

Database Analogy: If a collection is like a database table, a structure is like a single column in that table.

Managing Structures from Collections

Structures are created, edited, and deleted from within the collection interface. To access and manage structures:

  1. Navigate to a project page
  2. Click on a collection to view its details
  3. Locate the "Structures" section on the collection details page

Collection Page

Creating a Structure

To create a new structure:

  1. From the collection details page, click the "Create New" button in the Structures section
  2. Fill in the required information:
    • Name: A unique identifier for the structure (field name)
    • Description: Optional explanation of the structure's purpose
  3. In the same modal, define the properties for this field:
    • Select the appropriate data type
    • Configure validation rules
    • Set default values if needed
  4. Click "Create" to save the structure

Create Structure Modal

Structure Properties

When creating or editing a structure, you configure properties for that specific field:

  • Type: The type of data to be represented (Text, Email, Password, Markdown, Integer, etc.)
  • Required: Whether this field must be present in all records
  • Unique: Whether values must be unique across all records
  • Default: An optional default value
  • Min/Max: Constraints for strings (length) or numbers (value)
  • Pattern: A regular expression pattern for validation (strings only)

Field Types

Structures support various field types to model different kinds of data:

TypeDescriptionExample
TEXTBasic text data for names, descriptions, etc."Hello World"
EMAILEmail addresses with validation"user@example.com"
PASSWORDSecurely stored password strings"********"
MARKDOWNRich text with markdown formatting"# Heading\n\nParagraph with **bold** text"
INTEGERWhole number values42, -7
FLOATDecimal number values3.14159, -2.5
ENUMValue from a predefined list of options"pending" (from ["pending", "approved", "rejected"])
DATECalendar date values"2023-04-15"
DATETIMEDate and time values with timezone"2023-04-15T14:30:00Z"
MEDIAReferences to uploaded media files"uploads/image-123.jpg"
BOOLEANTrue/false valuestrue, false
UIDSystem-generated unique identifier"5f8d43e1b4ff..."
JSONArbitrary JSON data structures{"name": "John", "tags": ["important", "new"]}

Note on List/Array Types: Kinesis API supports array/list structures through the "array" flag. When enabled for a structure, it allows storing multiple values of the same type. Each element in the array must conform to the structure's validation rules (e.g., min/max values). In the interface, array elements are split by commas. This approach maintains type validation while providing flexibility for storing multiple related values within a single field. Arrays are useful for simple collections of values; for more complex relationships, consider using separate collections with UID references (similar to foreign keys in traditional databases).

Editing Structures

To modify an existing structure:

  1. From the collection details page, find the structure in the list
  2. Click the edit icon (pencil) next to the structure
  3. Make your changes in the structure editor
  4. Save your changes

Note: Modifying structures may affect existing data. Be cautious when changing field types or removing fields that contain data.

Deleting Structures

To remove a structure:

  1. From the collection details page, find the structure in the list
  2. Click the delete icon (trash) next to the structure
  3. Confirm the deletion when prompted

⚠️ Warning: Deleting a structure will affect any data that uses it. Ensure that no critical data depends on the structure before deleting.

Best Practices

When designing structures:

  1. Use Clear Naming: Choose descriptive, consistent names for structures and fields
  2. Start Simple: Begin with minimal structures and evolve them as needed
  3. Consider Validation: Use constraints to ensure data quality
  4. Think About Relationships: Plan how structures will relate to each other
  5. Document Your Design: Add clear descriptions to structures and fields
  6. Versioning Strategy: Consider how to handle structure changes over time
  • Collections - Managing collections that contain structures
  • Custom Structures - Creating reusable structure templates
  • Data - Working with data based on structures