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:
- Navigate to a project page
- Click on a collection to view its details
- Locate the "Structures" section on the collection details page
Creating a Structure
To create a new structure:
- From the collection details page, click the "Create New" button in the Structures section
- Fill in the required information:
- Name: A unique identifier for the structure (field name)
- Description: Optional explanation of the structure's purpose
- In the same modal, define the properties for this field:
- Select the appropriate data type
- Configure validation rules
- Set default values if needed
- Click "Create" to save the structure
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:
Type | Description | Example |
---|---|---|
TEXT | Basic text data for names, descriptions, etc. | "Hello World" |
Email addresses with validation | "user@example.com" | |
PASSWORD | Securely stored password strings | "********" |
MARKDOWN | Rich text with markdown formatting | "# Heading\n\nParagraph with **bold** text" |
INTEGER | Whole number values | 42 , -7 |
FLOAT | Decimal number values | 3.14159 , -2.5 |
ENUM | Value from a predefined list of options | "pending" (from ["pending", "approved", "rejected"]) |
DATE | Calendar date values | "2023-04-15" |
DATETIME | Date and time values with timezone | "2023-04-15T14:30:00Z" |
MEDIA | References to uploaded media files | "uploads/image-123.jpg" |
BOOLEAN | True/false values | true , false |
UID | System-generated unique identifier | "5f8d43e1b4ff..." |
JSON | Arbitrary 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:
- From the collection details page, find the structure in the list
- Click the edit icon (pencil) next to the structure
- Make your changes in the structure editor
- 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:
- From the collection details page, find the structure in the list
- Click the delete icon (trash) next to the structure
- 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:
- Use Clear Naming: Choose descriptive, consistent names for structures and fields
- Start Simple: Begin with minimal structures and evolve them as needed
- Consider Validation: Use constraints to ensure data quality
- Think About Relationships: Plan how structures will relate to each other
- Document Your Design: Add clear descriptions to structures and fields
- Versioning Strategy: Consider how to handle structure changes over time
Related Documentation
- Collections - Managing collections that contain structures
- Custom Structures - Creating reusable structure templates
- Data - Working with data based on structures