Skip to main content

Collections

Collections are database tables with additional metadata and configuration in TrackVision AI. They serve as the fundamental data modeling unit, representing structured data storage and management for your business operations.

Overview​

A collection represents a group of related data items that share the same structure and properties. Collections are the foundation of data organization in TrackVision AI, providing a schema-based approach to data management with powerful configuration options.

Each collection defines:

  • Field definitions and data types
  • Validation rules and constraints
  • Access permissions and security policies
  • Relationships with other collections
  • Display and interface configurations

Collection Types​

User Collections​

User collections are created directly in the database or via TrackVision AI to describe specific data models and configurations. These collections can be queried via APIs and represent your business data.

Examples:

  • Product catalogs and inventory
  • Location and facility data
  • Transaction and event records
  • Customer and supplier information
  • Custom business entities

System Collections​

System collections are automatically created collections required for TrackVision AI platform operation. These collections are prefixed with trackvision_ and power different system functionalities.

Built-in system collections include:

  • Users: User accounts and authentication
  • Roles: Permission groups and access control
  • Activity: System audit logs and user actions
  • Settings: Platform configuration and preferences
  • Files: File storage and media management
  • Folders: File organization and hierarchy
  • Permissions: Access control definitions
  • Presets: Saved user interface configurations

Collection Creation Requirements​

Naming Requirements​

  • Unique Name: Collection names must be unique across the platform
  • Case Sensitive: Names are case-sensitive for precision
  • Immutable: Collection names cannot be changed after creation
  • Conventions: Use snake_case for consistency (e.g., product_categories)

Primary Key Configuration​

Every collection requires a primary key field for unique item identification. TrackVision AI supports several primary key types:

Auto-Incremented Integer​

Sequential integer values starting from 1.

  • Use case: Simple collections with predictable growth
  • Pros: Efficient storage, fast queries
  • Cons: Exposes record count, not globally unique

Auto-Incremented Big Integer​

Sequential big integer values for large-scale collections.

  • Use case: Collections expecting millions of records
  • Pros: Handles very large datasets
  • Cons: Larger storage footprint

Generated UUID​

Universally unique identifiers generated automatically.

  • Use case: Distributed systems, data synchronization
  • Pros: Globally unique, secure, works across systems
  • Cons: Larger storage, less human-readable

Manually Entered String​

Custom string values entered manually or programmatically.

  • Use case: Collections with natural identifiers
  • Pros: Human-readable, integrates with external systems
  • Cons: Requires manual management, potential conflicts

Collection Configuration​

Basic Configuration​

Collection Setup​

  • Name: The database table name and collection identifier
  • Note: Internal description for documentation purposes
  • Icon: Visual representation in the platform interface
  • Color: Color coding for organization and visual distinction
  • Display Template: Defines how items are presented in lists and relationships

Visibility Settings​

  • Hidden: Hide collection from navigation (accessible via API)
  • Singleton: Restrict collection to contain only a single item
  • Archive: Enable soft deletion functionality for items

Advanced Configuration​

Content Management​

  • Content Versioning: Track changes and maintain revision history
  • Live Preview: Real-time preview of content changes
  • Manual Sorting: Enable drag-and-drop reordering of items
  • Item Duplication: Allow copying items with modifications

Accountability and Auditing​

  • Accountability: Automatically track creation and modification metadata
  • Activity Logging: Record all changes and user actions
  • Revision History: Maintain complete change history for compliance

Performance and Behavior​

  • Archive Value: Custom value for archived items
  • Sort Field: Default field for ordering collection items
  • Item Name Template: Template for generating item display names
  • Preview URL: Template for generating preview links

Collection Management​

Creation Methods​

Collections can be created and managed through multiple interfaces:

  1. Platform Admin Interface: Visual collection builder with forms
  2. REST API Endpoints: Programmatic collection creation and updates
  3. GraphQL Schema: Define collections using GraphQL syntax
  4. Database Migrations: Version-controlled schema changes
  5. Configuration Files: JSON-based collection definitions

Database Integration​

Introspection Support​

TrackVision AI supports introspection of existing database tables, allowing you to:

  • Import existing database schemas
  • Automatically detect field types and constraints
  • Preserve existing data and relationships
  • Gradually migrate to TrackVision AI management

Current Limitations​

  • Composite Keys: Not currently supported (single primary key required)
  • SQL Views: Virtual tables not supported as collections
  • Complex Constraints: Some advanced database constraints may not be preserved

Collection Updates​

Safe Updates​

  • Adding new optional fields
  • Modifying display configurations
  • Updating descriptions and documentation
  • Changing visibility settings

Breaking Changes​

  • Renaming collections (not supported - requires recreation)
  • Changing primary key type
  • Removing fields with data
  • Modifying field types incompatibly

Collection Relationships​

Collections can be connected through various relationship types:

  • One-to-Many: Parent collection to multiple child items
  • Many-to-One: Multiple items referencing single parent
  • Many-to-Many: Bi-directional relationships through junction tables
  • One-to-One: Exclusive relationships between collections

Performance Considerations​

Database Optimization​

  • Indexing: Automatically index primary keys and foreign keys
  • Query Performance: Consider field types and relationship complexity
  • Data Volume: Plan for collection growth and scaling requirements
  • Storage: Balance normalization with query efficiency

Interface Performance​

  • Display Templates: Use efficient templates for large collections
  • Field Selection: Limit displayed fields for better performance
  • Pagination: Implement appropriate pagination for large datasets
  • Caching: Leverage caching for frequently accessed collections

Best Practices​

Collection Design​

  1. Strategic Naming: Use clear, descriptive, consistent naming conventions
  2. Primary Key Selection: Choose appropriate primary key type for use case
  3. Field Organization: Group related fields logically using interfaces
  4. Relationship Planning: Design relationships during initial data modeling
  5. Documentation: Maintain clear notes and descriptions

Data Management​

  1. Validation Rules: Implement appropriate field validation
  2. Access Control: Apply proper permissions and security policies
  3. Data Integrity: Use relationships to maintain referential integrity
  4. Archive Strategy: Plan for data lifecycle and retention policies
  5. Backup Procedures: Implement regular backup and recovery procedures

Performance Optimization​

  1. Index Strategy: Index fields used in queries and filters
  2. Query Patterns: Design collections for expected query patterns
  3. Data Volume: Consider pagination and filtering for large datasets
  4. Relationship Depth: Limit deep relationship traversal in queries
  5. Monitoring: Track collection performance and optimize as needed

Maintenance and Growth​

  1. Version Control: Track schema changes in version control
  2. Migration Planning: Plan for schema evolution and data migration
  3. Testing: Test collection changes in development environments
  4. Documentation: Maintain up-to-date collection documentation
  5. Review Cycles: Regularly review collection design and usage patterns