...
All C3.ai Types are defined in a .c3typ file, stored in 'src' directory of a C3.ai Package. (We'll get to C3.ai Packages a little later). A .c3typ file can only define a single C3.ai Type. The .c3type file name must match the name of the C3.ai Type being defined.
First, we will describe the C3.ai Package, to download for this tutorial. Then, we will discuss the syntax, special keywords, fields, methods, and inheritance structure of C3.ai Types. Finally, we will review some examples.
...
To help familiarize yourself with the syntax for a C3.ai Type, let's look at how the 'SmartBulb' Type is defined in the lightbulbAD C3.ai Package:
...
/*
...
*
...
Copyright
...
2009-2020
...
C3
...
(www.c3.ai).
...
All
...
Rights
...
Reserved.
...
*
...
This
...
material,
...
including
...
without
...
limitation
...
any
...
software,
...
is
...
the
...
confidential
...
trade
...
secret
...
and
...
proprietary
...
*
...
information
...
of
...
C3
...
and
...
its
...
licensors.
...
Reproduction,
...
use
...
and/or
...
distribution
...
of
...
this
...
material
...
in
...
any
...
form
...
is
...
*
...
strictly
...
prohibited
...
except
...
as
...
set
...
forth
...
in
...
a
...
written
...
license
...
agreement
...
with
...
C3
...
and/or
...
its
...
authorized
...
distributors.
...
*
...
This
...
material
...
may
...
be
...
covered
...
by
...
one
...
or
...
more
...
patents
...
or
...
pending
...
patent
...
applications.
...
*/
...
/**
...
*
...
A
...
single
...
light
...
bulb
...
capable
...
of
...
measuring
...
various
...
properties,
...
including
...
power
...
consumption,
...
light
...
output,
...
etc.
...
*/
...
entity
...
type
...
SmartBulb
...
extends
...
LightBulb
...
mixes
...
MetricEvaluatable,
...
NLEvaluatable
...
type
...
key
...
"SMRT_BLB"
...
{
/**
...
* This bulb's
...
historical
...
measurements.
...
*/
...
bulbMeasurements:
...
[SmartBulbMeasurementSeries](smartBulb)
...
/**
...
* This bulb's
...
historical
...
predictions.
...
*/
...
@db(order='descending(timestamp)')
...
bulbPredictions:
...
[SmartBulbPrediction](smartBulb)
...
/**
...
* This bulb's
...
latest
...
prediction.
...
*/
...
currentPrediction:
...
SmartBulbPrediction
...
stored
...
calc
...
"bulbPredictions[0]"
...
/**
...
* This bulb's
...
historical
...
events.
...
*/
...
bulbEvents:
...
[SmartBulbEvent](smartBulb)
...
/**
...
* The latitude of this bulb.
*/
latitude: double
/**
* The longitude of this bulb.
*/
longitude: double
/**
* The unit of measurement used for this bulb's light output measurements.
*/
lumensUOM: Unit
/**
* The unit of measurement used for this bulb's power consumption measurements.
*/
powerUOM: Unit
/**
* The unit of measurement used for this bulb's temperature measurements.
*/
temperatureUOM: Unit
/**
* The unit of measurement used for this bulb's voltage measurements.
*/
voltageUOM: Unit
/**
* A SmartBulb is associated to a {@link Fixture} through a SmartBulbToFixtureRelation.
*/
@db(order='descending(start),
...
descending(end)')
...
fixtureHistory:
...
[SmartBulbToFixtureRelation](from)
...
/**
...
* The current Fixture to which this bulb is attached.
*/
currentFixture: Fixture stored calc 'fixtureHistory[0].(end
...
==
...
null).to'
...
/**
...
* Method to determine the expected lumens of a light bulb
*/
expectedLumens: function(wattage:
...
!decimal,
...
bulbType:
...
!string):
...
double
...
js
...
server
/**
...
* Returns the life span of this smartBulb
*/
lifeSpanInYears: function(bulbId:
...
string):
...
double
...
js
...
server
/**
...
* Returns the average life span of all smartBulbs.
*/
averageLifeSpan: function():
...
double
...
js
...
server
/**
...
* Returns the id of the smart bulb with the shortest recorded life span to date.
*/
shortestLifeSpanBulb: function():
...
string
...
js
...
server
/**
...
* Returns the id of the smart bulb with the longest recorded life span to date.
*/
longestLifeSpanBulb: function():
...
string
...
js
...
server
...
}
At a glance, a .c3typ file has the following components:
- Keywords, which define the name, inheritance, and properties of a C3.ai typeType
- fields are named, and their Types defined
- methods are named, their types are similar to function signatures.
- Additional annotations like '@db' can sometimes precede fields or methods.
- Types can inherit other types.
- Fields, which define attributes or data elements on a C3.ai Type
- Methods, which define business logic on C3.ai Types
- Annotations like '@db', which often precede fields or methods, and configure the behavior of a C3.ai type
- Constants such as strings or integers.
- Comments which aren't parsed by C3, and instead provide a message to the developer.
At a high level, the basic syntax to define C3.ai Type is as follows (originally from official C3.ai Type From a high level, the signature of a C3 Type definition looks like this: (originally from official C3.ai type documentation here: https://developer.c3.ai/docs/7.12.17/topic/mda-types
...
Everything within square brackets '[]' is optional.
C3.ai resources Resources on C3.ai Types generally:
- C3.ai developer documentationDeveloper Documentation
- C3.ai academy videos
- The TypeSystem Module: https://learnc3.litmos.com/course/3802349/module/7466519
- Types Overview
- C3 Types
- Type Definition
- The TypeSystem Module: https://learnc3.litmos.com/course/3802349/module/7466519
Keywords
A C3.ai Type definition is introduced using with a series of keywords, and names. These keywords tell the C3 AI Suite how to construct this type, how to store it internally, and whether it inherits fields and methods from other already defined TypesC3.ai Types. We describe each:
- type: All C3 Types use .c3typ files have the keyword 'type'. This indicates to keyword tells the C3 AI Suite that this is file defines a C3.ai Type definition.
- entity: The keyword 'entity' keyword indicates that the type mixes in the 'Persistable' type and is stored internally to C3 in a table somewhere. We can mix in Persistable instead but this keyword makes the Type definition shorter and easier to readthe C3.ai Type is a 'Persistable' (i.e., needs to be stored in a database in the C3 AI Suite). Since a large majority of the Types on the C3 AI Suite are persistable, this is a good keyword to have.
- mixes: A type which specifies `mixes AnotherType` inherits the fields and methods of the other type. Multiple Types can be mixed in, and mixes do not change the way the type is stored internally.
- remixes: A type which specifies `remix` defines a modification of an existing type.
- extends: A type which specifies `extends AnotherType` is a special type of of mixin. This mixin subclasses a persistable type in a special way, The original Types along with the new Types are stored together in the same table. required as well, is the `type key` modifier which describes the key to use when storing the new type internally.
- extendable: A keyword indicating that a Type can be extended. The C3 AI Suite will create the internal table for this type with an additional field called the 'key' which will be used to distinguish the different varieties of this base type.
- type key: A set of keywords indicating the Key value to use when storing a type which extends another type. schema name: A set of keywords indicating the name of the table to use to store the Type.
- C3.ai Types are Persistable, 'entity' is an important keyword to include in .c3typ files.
- mixes: Adding the keyword `mixes AnotherType`, a C3.ai Type inherits the properties (e.g., fields, methods) of `AnotherType'. A C3.ai Type can mix-in multiple Types.
- remixes: Adding the keyword`remix AType`, allows C3.ai developer to modify an existing C3.ai Type (e.g., add new fields or methods, update existing fields or methods). Re-mixing is useful when you don't have access to the original .c3type file for a particular C3.ai Type, but wish to edit that C3.ai Type.
- extends: C3.ai developers often add the keyword `extends AnotherType`, to define a subclass of a particular C3.ai Type (e.g., SmartBulb extends Lightbulb). The extension Type (i.e., Smartbulb) inherits all the fields and methods of the original Type (i.e., Lightbulb). Additionally, data associated with the extension and original C3.ai Types are stored in the same database table. Therefore, you must specify a `type key`(on the extension Type), so the C3 AI Suite can distinguish data associated with the extension and original C3.ai Types. Please note, a C3.ai Type can only extend ONE other Type.
- extendable: All extended Types (i.e., Lightbulb) MUST be marked with the keyword "extendable". Under the covers, the keyword "extendable" tells the C3 AI Suite to add a field (called 'key') to the database table, storing the extended (or base) C3.ai Type. This 'key' field is used to distinguish data associated with different varieties of the extended C3.ai Type.
- type key: All extension types (i.e., Smartbulb) MUST BE marked with the keyword 'type key VALUE' (e.g., "type key SMRT_BLB").
- schema name: A set of keywords indicating the name of the database table, used to store data for a Persistable C3.ai Type. Developer specify a schema name to customize database table names.
To learn more about C3.ai Type Definitions, please see the C3.ai resources here:
- Developer Documentation
- C3.ai Academy Videos
- The TypeSystem Module
- Persistable Types
- Type Inheritance
- The TypeSystem Module
Primitive Types
As a basis for many fields, the C3 AI Suite defines many 'primitive' types. These are basic types like 'int' and 'double. Primitive Types are given to the developer by the platform and new ones require backend C3 support to define. Most DTI researchers will not be defining these, but using those that already exist.
...