Custom Schemas

Custom Schemas in Unbody allow you to define and manage your own data structures. This flexibility enables developers to handle unique data requirements, extend built-in schemas, and integrate deeply with their applications.

What Are Custom Schemas?

Custom Schemas let you:

• Create your own collections (data tables).
• Add custom fields (columns) to those collections.
• Extend built-in schemas (e.g., ImageBlock, VideoFile) with additional fields.

For example:

• Add a chapter field to VideoFile for storing extracted video chapters.
• Create a custom collection called BlogPost to handle rich metadata for articles.

Why Use Custom Schemas?

• Flexibility: Adapt data structures to your app’s unique needs.
• Extensibility: Extend existing schemas instead of starting from scratch.
• AI-Ready: Customize schemas to include fields optimized for vectorization and enrichment.

Configuring Custom Schemas

Custom Schemas can be configured via the Dashboard or programmatically using the Admin API.

1. Dashboard Setup

1. Go to your Project Settings.
2. Navigate to Custom Schemas.
3. Define your collections and fields.
4. Save and apply the schema to your project.

2. Admin API Configuration

You can define and manage Custom Schemas programmatically. Here’s how:

Example: Creating a Custom Schema

import { UnbodyAdmin, CustomSchema, ProjectSettings } from 'unbody/admin'
 
// Initialize Admin API
const admin = new UnbodyAdmin({
  auth: {
    username: '[admin-key-id]',
    password: '[admin-key-secret]',
  },
})
 
// Define a new custom schema
const customSchema = new CustomSchema()
 
// Create a custom collection with fields
const blogPostCollection = new CustomSchema.Collection('BlogPost')
blogPostCollection.add(new CustomSchema.Field.Text('title', 'Blog Title'))
blogPostCollection.add(new CustomSchema.Field.Text('content', 'Blog Content'))
blogPostCollection.add(new CustomSchema.Field.Date('publishedAt', 'Published Date'))
 
// Add the collection to the schema
customSchema.add(blogPostCollection)
 
// Save the schema to the project
const project = await admin.projects.get({ id: '[project-id]' })
const settings = project.settings.set(customSchema)
await project.updateSettings(settings)
 
console.log(`Custom Schema added to project: ${project.name}`)
 

Key Components of Custom Schemas

1. Collections

Collections are the top-level entities in Custom Schemas, similar to tables in a database.

• Example: BlogPost, Product, CustomUser.

2. Fields

Fields define the structure of data within a collection.

Available Field Types

3. Extending Built-in Schemas

Built-in schemas like VideoFile or TextDocument can be extended with custom fields.

Example: Adding a Custom Field to VideoFile

const videoFileCollection = new CustomSchema.Collection('VideoFile')
videoFileCollection.add(
  new CustomSchema.Field.Text(
    'chapter',
    'Extracted Chapters',
    true // Indicates an array field
  )
)
customSchema.extend(videoFileCollection)
 

4. Field Arguments

When defining fields, the following arguments are available:

• name (string): Field name in camelCase.
• description (string): Field description.
• array (boolean): Whether the field stores an array of values.
• tokenization (string): Tokenization strategy for text fields (word, field, lowercase, whitespace).
• skipVectorization (boolean): If true, skips vectorization for this field.

Best Practices

1. Naming Conventions:
   • Use PascalCase for collections (e.g., BlogPost).
   • Use camelCase for fields (e.g., publishedAt).
2. Avoid Redundancy:
   • Extend built-in schemas instead of duplicating functionality.
3. Optimize for AI:
   • Use tokenization wisely for text fields to improve vectorization.
4. Cross-References:
   • Use Field.Cref to link collections for relational data.

This detailed explanation of Custom Schemas ensures developers can leverage their full potential, from setup to advanced configurations. Let me know if you want further elaboration on any section!