Declarative Objectivity (DO) Language : Schema Statements
Schema Statements
Schema statements enable you to display or update portions of a federated database’s schema, which is the language-independent data model that describes all the classes used in a particular federated database.
A schema statement is an instruction that performs an action and, in most cases, returns a value. Each statement starts with a key phrase, contains schema clauses or other arguments, and ends with a semicolon.
 
Statement
Action
Displays the schema description of a class.
Displays a list of class in the federated database’s schema.
Displays the schema descriptions of all classes in the federated database’s schema.
Modifies the schema of a federated database.
Note:Examples in the schema-statement topics are based on the Rental Fleet Sample Schema.
Note:These statements work with a federated database’s schema. For statements that work with persistent data, see Data Statements.
About Schemas
A schema is a federated database’s representation of the particular types of data that can be stored persistently in that federated database. Because objects are the fundamental units of storage for persistent data, a schema contains descriptions of the classes to which those objects belong.
Schema Classes
A federated database’s schema must describe each class that is to have objects saved persistently in the federated database. Every schema class is either:
A referenceable class (also called persistence-capable)
An embeddable class (also called non-persistence-capable)
Each persistent object of a referenceable class has a unique object identifier (OID) within the federated database, so it can be stored and found independently of other stored objects. Such persistent objects can be referenced by other objects. To create a referenceable class, see Describing a New Referenceable Class.
In contrast, an object of an embeddable class is stored only as a part of another object. That is, the embedded object’s values are stored among the values of the object that embeds it. An embedded object cannot be referenced or otherwise accessed independently of the top-level referenceable object that encloses it. To create an embeddable class, see Describing a New Embeddable Class.
Schema Namespaces
Schema classes may optionally be defined in schema namespaces, which serve as name scopes for grouping sets of classes. Schema namespaces enable class names to be reused in the same schema without causing naming collisions, and are analogous to the namespaces (or packages) supported by various programming languages.
Schema classes that are not defined in any schema namespace are said to be in the default namespace.
Schema Class Descriptions
The description for a particular schema class contains the following information:
The name of the class.
The name of the schema namespace, if any.
The name of the class’s immediate superclass, if the class inherits from another schema class; see Schema Class Inheritance, below.
Whether the class is referenceable or embeddable.
A description of every persistent attribute in the class. Persistent attributes define the values that can be stored by an object of the class. Certain attributes represent relationships to other classes.
Each attribute description includes a name and a data type. The data type of an attribute may be one of the built-in data types or a user-defined embeddable class described in the same schema; see Overview of Attribute Data Types, below.
When a class has been successfully added to a schema, the federated database assigns that class a unique identifying type number.
A schema class description specifies the overall shape of a storable class, which, in turn, specifies how each object of the class is laid out in persistent storage. The data type of each attribute in a class determines the size of the corresponding value stored by each object of the class. The order of stored values is automatically calculated to optimize data packing. A federated database uses a class’s shape information when allocating storage space for new objects, and when reading and writing existing objects.
Schema Class Inheritance
A schema class can have a single direct superclass within a federated database’s schema.
A referenceable class may inherit only from another referenceable class.
An embeddable class may inherit only from another embeddable class.
As in object-oriented programming, when one schema class inherits from another, the subclass holds values for the attributes defined by the superclass, in addition to holding values for its own attributes.
For example, say the referenceable class Vehicle has a subclass GasVehicle. The subclass has all attributes defined by the Vehicle class (license, available, model, atStall, and so on), plus additional attributes such as tankSize.
A schema class may have any number of indirect superclasses.
Schema Class Polymorphism
The schema of a federated database supports full polymorphism for referenceable classes. As in object-oriented programming, this means you can use references to a subclass wherever references to the superclass are expected.
For example, say the referenceable class Vehicle has two subclasses, GasVehicle and HybridVehicle. Now assume that the Stall class has an attribute called occupiedBy, whose type is a reference to Vehicle. You could set a particular Stall object’s occupiedBy attribute to reference a Vehicle object, a GasVehicle object, or a HybridVehicle object. If, however, GasVehicle was chosen instead of Vehicle as the attribute’s referenced class, then each Stall’s occupiedBy attribute could only be set to reference a GasVehicle object.
Polymorphism is not supported for embeddable classes. For example, say the embeddable class Address has two subclasses UsAddress and InternationalAddress. Now assume that you need to define an address attribute in the Customer class. If you choose Address as the attribute type, then only objects of type Address can be embedded within a Customer object; the attribute cannot be set to an object of either subclass. (This is because the Customer object has simply not reserved sufficient space for embedding any object with more attributes than an Address.)
Note:Inheritance among embeddable classes can still be useful for enforcing common attributes among subclasses, even if polymorphism is not a benefit.
Interoperability
A federated database’s schema is shared by all tools and applications that access the federated database. Because the schema is independent of any particular programming language or architecture, it can be shared by all applications and tools that:
Use one of the supported languages or interfaces, such as the DO query language or Objectivity REST.
Run on one of the Objectivity-supported platforms.
The schema enables such applications and tools to interoperate (create, read, update, and delete stored objects) in the same federated database.
Overview of Attribute Data Types
The table below summarizes the data types that are supported for the attributes of classes in a federated database’s schema. Related types are presented as a “family” identified by a logical type, such as Integer or String. Within some families, the related types are distinguished by one or both of the following characteristics:
Encoding
Representation used for a stored value of the type. Encodings are specific to the logical type—for example, Unsigned for Integer, and Utf8 for String.
Storage
Storage reserved for a value of the type. Storage is specific to the logical type—for example, B16 (16-bit) for Integers, and Variable for Strings.
For details about defining attributes of these data types, see Attribute Structures and its subtopics.
 
Family of Data Types
Description
Boolean
Values that are either true or false
   Binary encoding
Byte
Data type for:
8-bit Boolean values
Character
Characters within a string
   Binary encoding
B8, B16,
B32
Data types for:
8-bit, 16-bit, and 32-bit character values.
Integer
Signed or unsigned whole numbers
   Signed encoding
 
B8, B16, B32, B64
Data types for:
Signed 8-bit, 16-bit, 32-bit, and 64-bit integer values.
   Unsigned encoding
B8, B16, B32, B64
Types support:
Unsigned 8-bit, 16-bit, 32-bit, and 64-bit integer values.
Real
Real numbers with a fractional part
   IEEE encoding
B32, B64
Data types for:
32-bit and 64-bit real (floating-point) values.
Guid
GUID (globally unique identifier)
   Binary encoding
B128
Data type for:
128-bit GUID or UUID (universally unique identifier).
String
Sequences of characters
   Byte encoding
Fixed, Variable, Optimized
Data types for:
Strings that use an 8-bit character encoding such as ASCII or ISO-Latin1, and are either fixed-length, variable-length, or optimized for (but not limited to) a particular length.
   Utf8 encoding
   Utf16 encoding
   Utf32 encoding
Fixed, Variable, Optimized
Data types for:
Strings that use Unicode UTF-8, UTF-16, or UTF-32 character encoding, and are either fixed-length, variable-length, or optimized for (but not limited to) a particular length.
Date
Dates on the Gregorian calendar, with day precision
   OBJY encoding
Data type for:
4-byte date values from January 1, 0001 to December 31, 9999.
Time
Times in the 24-hour clock format, with 100-microsecond precision
   OBJY encoding
Data type for:
4-byte time values from 00:00:00.0000 (midnight) to 23:59:59.9999.
DateTime
Datetimes (timestamps) for with 100-nanosecond precision, with or without time-zone offset
   OBJY encoding
Datetime, DatetimeOffset
Data type for:
Datetime values from January 1, 0001, 00:00:00.0000000 to December 31, 9999, 23:59:59.9999999.
 
May be:
8-byte values expressed either in the local time standard or in the Coordinated Universal Time (UTC) standard.
16-byte values representing a local time in a time zone that is expressed as an offset (number of minutes between local time and UTC).
Interval
Timespans between two dates, times or datetimes, with 100 nanosecond precision
   OBJY encoding
Data type for:
8-byte interval values from 5,000,000 days to -5,000,000 days.
Reference
Object references to persistent instances of a user-defined referenceable schema class
 
Data type for:
Object references encapsulating the Objectivity/DB object identifier (OID) of a persistent object of a referenceable class described in the schema.
 
May be:
Unidirectional, to model one-way relationships between persistent objects.
Bidirectional (when paired with an inverse), to model two-way relationships between persistent objects.
 
Used as:
Values of reference attributes, to model to-one relationships.
Elements of collection attributes, to model to-many relationships.
Object
Values that are objects of a user-defined embeddable schema class
Data type for:
Embedded-object attributes. When an object is embedded, its attributes are stored among the attributes of the enclosing object.
List
Ordered groupings of potentially non-unique elements
 
Data types for:
Fixed-size or variable-size arrays of elements of any type.
To-many bidirectional or unidirectional relationships to persistent objects.
Scalable lists of references to persistent objects.
Map
Ordered or unordered groupings of unique keys that lead to potentially non-unique values
 
Data types for:
Maps whose keys are strings.
Maps whose keys are references to persistent objects.
Set
Ordered or unordered groupings of unique elements
 
Data types for:
Sets of references to persistent objects.
Schema Evolution
Schema evolution is the process of modifying the schema of a federated database over time. When a class is first created, it is identified by a unique class number, which is identical to its shape number. If the class is evolved, a new description is added to the schema and the shape number is incremented. New objects use the new class description, and existing objects are converted to use the new description the next time they are accessed.
When accessed by name, the class automatically gets the latest shape number.
Consequences of Schema Evolution
Schema evolution can result in changes to your data, depending on the type of schema change. Any existing objects that were created under the original class description will be modified when they are next accessed. The process of converting objects to match the new class shape is called object migration.
Note:Certain schema changes can result in data loss during object migration. For example, if you delete an attribute from an existing class, each existing object of that class will be modified to remove the attribute in question and discard that attribute’s value.
The following table describes the consequences of various schema modifications on existing objects of the given class. Consider any changes carefully before implementing them.
Schema Change
Consequences for Existing Objects
Add an attribute
Space for the new attribute is added to objects of that class and its subclasses. The shape number of the class is incremented.
Delete an attribute
The attribute is removed from objects of that class and the values are lost. The shape number of the class is incremented.
Rename an attribute
The attribute is renamed and its value is retained. The shape number of the class remains the same.
Delete a class
Objects of the class become inaccessible after the class is deleted.
 
Note: Before deleting a class, you should remove all objects of that class from the federated database.
Rename a class
Objects can be accessed using the new class name. The shape number of the class remains the same.