C3 AI Documentation Home

Create an Entity

An object model in a C3 AI application consists of multiple entities joined together in a relational model. Each entity represents a real-world object or concept, such as a location or organization.

For example, an object model for a global temperature tracking application has objects for continents, countries, and cities.

In this tutorial, you begin building an object model for a global data tracking application. Start by creating a simple entity Type in the object model. In later tutorials, you add additional capabilities to this Type and expand your object model.

Define an entity

Use the C3 AI VS Code Extension to create the .c3typ file for your new entity.

With the C3 AI VS Code extension, you create new persistable Types by creating .c3typ files in the src/entities folder of your package. Create a new Country Type to represent a country in a global data tracking application.

To learn about the core design principles for development of the C3 Agentic AI Platform and applications, see C3 AI Design Principles.

The syntax to create a type consists of the following components:

  • Type name: The Type name must match the filename of the .c3typ file.
  • Type declaration: The entity type syntax creates a Persistable Type, which is a Type that can store data.
    • Persistable Types are saved as .c3typ files in the src/entities folder of your package.
  • Comments: The comments in the .c3typ file create documentation for the Type and its fields.

The following code block displays the completed Country Type:

Type
/**
 * Country.c3typ
 * A single country in the global data model.
 */
entity type Country {
}

Currently, the Country Type does not have any fields beyond the default options.

Learn how to add new fields to an existing Type in the next section.

Type fields

Fields are used to add additional dimensions to Types. In persistable Types, fields represent columns when the Type is queried.

Fields are declared in the .c3typ file with the field name and data type separated by a colon.

Type
/**
 * MyType.c3typ
 * An example Type
 */
entity type MyType {
  // An example of some fields with common data types
  myString: string
  myInt: int
  myDouble: double
}

In this tutorial, Type names use the Pascal Case, while field names use Camel Case. The following code block adds some basic fields to the Country Type:

Type
/**
 * Country.c3typ
 * A single country in the global data model.
 */
entity type Country {
  // The name of this country
  name: string
  // The three-letter country code defined in the ISO 3166-1 standard for this country
  alpha3Code: string
}

Add the new fields to the Country Type by editing the Country.c3typ file from the previous step.

Field constraints

Constraints are used to add additional controls to the data stored in fields.

  • Use the enum keyword in a field declaration to limit the value options to a specified list.
  • Use an exclamation point (!) before the data type to mark a field as required and prevent null values.

The following code block adds additional constraints to the fields in the Country Type:

Type
/**
 * Country.c3typ
 * A single country in the global data model.
 */
entity type Country {
  // The name of this country
  name: !string
  // The three-letter country code defined in the ISO 3166-1 standard for this country
  alpha3Code: !string
}

Add the above field contraints to the Country Type to complete the definition of this Type.

Next steps

Was this page helpful?