%FOI.Schema

SQL Table Name: %FOI.Schema

Unified Schema

Overview

Unified Schema is a mechanism for defining schemas that are independent of any platform and that can be used to generate platform dependent implementations, keeping those generated implementations synchronized between the various platforms that interact with those schemas.

%FOI.Schema defines the Unified Schema and implements an interface to create, generate server implementations, and retrieve metadata.

Model

The unified schema model is inspired by AVRO but is not AVRO. A schema has a type and that type can be simple or complex, it can embed the definition of other types or it can reference other types by name. A schema is identified by name. Name is qualified by namespace. A schema is a record type in AVRO terminology. It contains fields, parameters, embedded named types, and indices. Each of these entities is described in more detail in the properties and methods sections.
It is important to not confuse the term 'namespace' in the context of a Schema and 'namespace' in the context of Iris. In the context of %FOI.Schema, a 'namespace' is a schema name qualifier.

Interface

%FOI.Schema is a persistent class and the persistent interface, while fully supported, should be considered to be internal. The primary interface of Unified Schema is not implemented by this class but in the various supported platforms. Methods implemented by this class can still be invoked by privileged users. Refer to individual methods of this class for more detai.

Public Methods

compileSchema Compile a schema.
compileSchemaList Compile each schema named in the given %Library.List object.
compileSchemas Compile each schema named in the given %Library.DynamicArray.
deleteSchema Delete the schema definition.
deleteSchemaExtent Delete the persistent extent in the given namespace for the server implementation linked to the given schema.
getNamespaces Return a JSON serialized array containing the names of the namespaces available on this system.
getClasses Return a JSON serialized array of the classes in the given namespace.
getSchemas Return a JSON serialized array of schemas defined in the given namespace.
getSchema Return the unified schema for the given namespace and schema name.
getRecordDefinition Return the record definition for the given namespace and schema name.
uncompileSchema Uncompile a schema.

Property Inventory

Method Inventory

Parameters

parameter DEFAULTGLOBAL = ^IRIS.FOI.MD;
Inherited description:

If a persistent class uses %Storage.Persistent then the DEFAULTGLOBAL parameter is used as the default global root for the values of the storage keywords COUNTERLOCATION, DATALOCATION, IDLOCATION, INDEXLOCATION and STREAMLOCATION in the active storage definition. DEFAULTGLOBAL is only used to generate location keyword values that are not already defined. The location value is constructed by adding a location type to the end of DEFAULTGLOBAL. For example, if DEFAULTGLOBAL = "^GL.Account" the compiler will generate DATALOCATION = ^GL.AccountD.

If USEEXTENTSET is true, then DEFAULTGLOBAL is used as the default extent location.


The location types are:
LocationType
COUNTERLOCATIONC
DATALOCATIOND
IDLOCATIOND
INDEXLOCATIONI
STREAMLOCATIONS
parameter USEEXTENTSET = 1;
Inherited description:

If a persistent class uses %Storage.Persistent then the USEEXTENTSET parameter is used to specify the global naming strategy used by the default storage class (%Storage.Persistent). If TRUE, then global names are generated for each index that is not already allocated a LOCATION in the active storage definition.

If the storage definition specifies EXTENTLOCATION then that value is used as the base reference for all globals assigned to indices that do not have an explicit LOCATION assigned.

The global name generator for USEEXTENTSET = TRUE honors the package prefix defined in the Package Definition. If none is defined then the package prefix is generated using a based-62 encoded integer produced from CRC32 of the package name. The specific class identifier is generated from the unqualified class name using the same hash (class->crc32->base62) to form EXTENTLOCATION. Specific index suffixes are produced using a generated offset that is local to the first persistent class with an enumerated extent in which the index appears (either defined or inherited).

There are several factors that influence the generation of EXTENTLOCATION:

  1. If the EXTENTLOCATION keyword is defined then its value is used,
  2. If the DEFAULTGLOBAL class parameter is defined then its value is used,
  3. otherwise, the value is generated as two dot delimited segments. The first segment is either the defined package prefix retrieved from the package definition global or, if none is defined, a hash of the package name. The second segment is generated by a hash of the unqualified class name. The hash used is a base 62 encoded CRC32 of the value. For example, Sample.Person produces ^EW3K.wPC9 if no package prefix is defined.
The EXTENTLOCATION value is used as the base for specific globals allocated to indices. Each index is assigned an offset that is incremented from 1 by 1, offset = 1 is reserved for the IDKEY index.

EXTENTLOCATION is specific to each class. When a persistent class extends another persistent class, forming a subextent, then the subclass's EXTENTLOCATION is specific to that subclass. The index location for any inherited index is already defined specifically in the super class so the subclass's EXTENTLOCATION will only be used as the base for any index that originates in the subclass. For example, Sample.Employee extends Sample.Person. The EXTENTLOCATION generated for Sample.Person is ^EW3K.wPC9 and the EXTENTLOCATION for Sample.Employee is ^EW3K.D1Ex. Since Sample.Employee inherits several indices from Sample.Person, the global name assigned to each of those indices is already defined and inherited by Sample.Employee. However, any index defined in Sample.Employee and not inherited from Sample.Person will be assigned a global name based on Sample.Employee's EXTENTLOCATION, not on Sample.Person's EXTENTLOCATION. In other words, the EXTENTLOCATION storage keyword is not inherited.

The following tables show the indices and locations for Sample.Person and Sample.Employee. Notice the last index in the Sample.Employee table:

Class = Sample.Person
IndexLocation
IDKEY^EW3K.wPC9.1
$Person^EW3K.wPC9.2
NameIDX^EW3K.wPC9.3
SSNKey^EW3K.wPC9.4
ZipCode^EW3K.wPC9.5
Class = Sample.Employee extends Sample.Person
IndexLocation
IDKEY^EW3K.wPC9.1
$Person^EW3K.wPC9.2
NameIDX^EW3K.wPC9.3
SSNKey^EW3K.wPC9.4
ZipCode^EW3K.wPC9.5
$Employee^EW3K.D1Ex.2

Any generated global index locations and EXTENTLOCATION are updated back into the active storage definition after the class is compiled.

If USEEXTENTSET is FALSE, then global names are generated using the package-hash.class-hashSuffix strategy. For example, ^Sample.PersonD and ^Sample.PersonI("SSNKey") are globals used by Sample.Person and specific index structures are all stored in ^Sample.PersonI with the index name used as the first subscript.


Properties

property class as %Dictionary.ClassDefinition;
The name of the IRIS Server class that implements this schema.
Property methods: classGet(), classGetObject(), classGetObjectId(), classGetStored(), classGetSwizzled(), classIsValid(), classNewObject(), classSet(), classSetObject(), classSetObjectId(), classToSchema(), classUnSwizzle()
property fields as %Library.DynamicArray;
JSON Array of field definitions. An array is used to preserve order.
Property methods: fieldsGet(), fieldsGetObject(), fieldsGetObjectId(), fieldsGetStored(), fieldsGetSwizzled(), fieldsIsValid(), fieldsNewObject(), fieldsSet(), fieldsSetObject(), fieldsSetObjectId(), fieldsUnSwizzle()
property fullname as %String (MAXLEN = 220) [ Calculated , Required ];
Derived from namespace and name. This is the fully qualified schema name.
Property methods: fullnameCompute(), fullnameDisplayToLogical(), fullnameGet(), fullnameIsValid(), fullnameLogicalToDisplay(), fullnameLogicalToOdbc(), fullnameNormalize(), fullnameSQLCompute()
property generatedBy as %String (MAXLEN = 220);
generatedBy defines the origination of the schema, either a client such as 'xep' or the server. If generatedBy is not null then it must match the request generatedBy when replacing an existing schema definition.
Property methods: generatedByDisplayToLogical(), generatedByGet(), generatedByGetStored(), generatedByIsValid(), generatedByLogicalToDisplay(), generatedByLogicalToOdbc(), generatedByNormalize(), generatedBySet()
property indices as %Library.DynamicArray;
A JSON Array of index definitions.
Property methods: indicesGet(), indicesGetObject(), indicesGetObjectId(), indicesGetStored(), indicesGetSwizzled(), indicesIsValid(), indicesNewObject(), indicesSet(), indicesSetObject(), indicesSetObjectId(), indicesUnSwizzle()
property name as %String (MAXLEN = 220);
Schema Name. This must be a valid objects identifier.
Property methods: nameDisplayToLogical(), nameGet(), nameGetStored(), nameIsValid(), nameLogicalToDisplay(), nameLogicalToOdbc(), nameNormalize(), nameSet(), namedTypesGet(), namedTypesGetObject(), namedTypesGetObjectId(), namedTypesGetStored(), namedTypesGetSwizzled(), namedTypesIsValid(), namedTypesNewObject(), namedTypesSet(), namedTypesSetObject(), namedTypesSetObjectId(), namedTypesUnSwizzle(), namespaceDisplayToLogical(), namespaceGet(), namespaceGetStored(), namespaceIsValid(), namespaceLogicalToDisplay(), namespaceLogicalToOdbc(), namespaceNormalize(), namespaceSet()
property namedTypes as %Library.DynamicObject;
A JSON formatted object containing properties whose value is a type definition.
Property methods: namedTypesGet(), namedTypesGetObject(), namedTypesGetObjectId(), namedTypesGetStored(), namedTypesGetSwizzled(), namedTypesIsValid(), namedTypesNewObject(), namedTypesSet(), namedTypesSetObject(), namedTypesSetObjectId(), namedTypesUnSwizzle()
property namespace as %String (MAXLEN = 220);
Schema Namespace. This can be a simple string or a dot delimited string.
Property methods: namespaceDisplayToLogical(), namespaceGet(), namespaceGetStored(), namespaceIsValid(), namespaceLogicalToDisplay(), namespaceLogicalToOdbc(), namespaceNormalize(), namespaceSet()
property parameters as %Library.DynamicObject;
Schema parameters.
Property methods: parametersGet(), parametersGetObject(), parametersGetObjectId(), parametersGetStored(), parametersGetSwizzled(), parametersIsValid(), parametersNewObject(), parametersSet(), parametersSetObject(), parametersSetObjectId(), parametersUnSwizzle()
property recordMetadata as %Library.DynamicObject;
This is a JSON object defined in the same manner as the namedTypes property. It defines the data record format for the server implementation of this schema.
Property methods: recordMetadataGet(), recordMetadataGetObject(), recordMetadataGetObjectId(), recordMetadataGetStored(), recordMetadataGetSwizzled(), recordMetadataIsValid(), recordMetadataNewObject(), recordMetadataSet(), recordMetadataSetObject(), recordMetadataSetObjectId(), recordMetadataUnSwizzle()
property schema as %Library.DynamicObject;
A JSON formatted object containing the base schema properties.
Property methods: schemaGet(), schemaGetObject(), schemaGetObjectId(), schemaGetStored(), schemaGetSwizzled(), schemaIsValid(), schemaNewObject(), schemaSet(), schemaSetObject(), schemaSetObjectId(), schemaToClass(), schemaToRecord(), schemaUnSwizzle()

Methods

classmethod %FromJSON(str As %RawString) as %FOI.Schema [ Language = objectscript ]

Import a schema or multiple schemas from JSON. The input value can be a string formatted as JSON, an instance of %Library.DynamicAbstractObject or a stream containing JSON. If the input JSON is an array then each element of the array is expected to be a schema and each will be imported.

The input is parsed and placed in instances of this class. The response is an instance of this class, in keeping with the %FromJSON() interface, or in the case where multiple schema are presented in an array, the response is an array (%Library.DynamicArray) of schema instances.

Schemas imported from JSON are automatically saved.

method %ToJSON(stream As %Stream.Object) as %Library.String [ Language = objectscript ]
Return the full schema definition rendered in the same format as %FromJSON() expects. This method is use by XEP Clients to retrieve a full schema definition. For only the recordMetadata, clients can simply ask for the schema's recordMetadata object.
classmethod compileSchema(schemaName As %String(MAXLEN=220), namespace As %String(MAXLEN=220)="") [ Language = objectscript, SQLProc = compileSchema ]

Compile the schema. Generate the server implementation if the schema originates from a client or link to an existing server implementation if the schema originates on the server. If no error is encountered then the server implementation is compiled. This method throws an exception if any errors are encountered.

schemaName Name of the schema to compile
namespace The namespace of the schema. If namespace is null or empty then schemaName is expected to be a fully qualified name.

classmethod compileSchemaList(list As %List) as %Library.String [ Language = objectscript ]

Compile each schema contained in the %List object. This method just repackages the %List instance as a JSON array and dispatches to compileSchemas().

list The %Library.List object containing the names of the schemas to compile.

classmethod compileSchemas(schemas As %Library.DynamicAbstractObject) as %Library.String [ Language = objectscript ]

compileSchemas accepts an array of schema names and generates the server implementation for each schema. If no errors are encountered then all server implementations generated are compiled. This method does not return any useful value (null on success) but exceptions are thrown for any failures.

For an IRIS Server, the implementation of a schema is a class definition.

schemas A JSON serialized array or a %Library.DynamicArray containing the names of the schemas to compile.

classmethod deleteSchema(schemaName As %String(MAXLEN=220), namespace As %String(MAXLEN=220)="") [ Language = objectscript, SQLProc = deleteSchema ]

Delete the schema definition from the specified namespace (defaults to the current namespace). If the schema originates from a client then the server implementation linked to the schema will also be deleted. This method throws an exception if any errors are encountered.

schemaName Name of the schema to be deleted
namespace The namespace of the schema. If namespace is null or empty then schemaName is expected to be a fully qualified name.

classmethod deleteSchemaExtent(schemaName As %String(MAXLEN=220), namespace As %String(MAXLEN=220)="") [ Language = objectscript, SQLProc = deleteSchemaExtent ]

Delete the persistent extent in the given namespace for the server implementation linked to the given schema. This method throws an exception if any errors are encountered.

schemaName Name of the schema
namespace The namespace of the schema. If namespace is null or empty then schemaName is expected to be a fully qualified name.

classmethod fromJSON(schemasJson As %RawString) as %RawString [ Language = objectscript ]
fromJSON() accepts either a JSON serialized schema definition or an array of JSON serialized schema definitions. It then imports them into the current IRIS Namespace and returns a JSON serialized array of the names of the schemas successfully imported.
classmethod generateSchema(className As %String(MAXLEN=220)) as %String [ Language = objectscript, SQLProc = generateSchema ]
generateSchema - generate a Unified Schema from an existing class definition.

className Name of the class to generate a unified schema from.
return Return value is a JSON formatted array containing the full names of all schemas generated.

classmethod getClasses() as %String [ Language = objectscript, SQLProc = getClasses ]

getClasses - return a JSON array of the names of classes defined in the current namespace.

return Return value is a JSON formatted array of class names.

classmethod getNamespaces() as %String [ Language = objectscript, SQLProc = getNamespaces ]

This method returns a JSON serialized array containing namespaces accessible on this system. This class method can be invoked by SQL as a function or a procedure (%FOI.getNamespaces() or ? = call %FOI.getNamespaces()).

classmethod getRecordDefinition(schemaName As %String(MAXLEN=220), namespace As %String(MAXLEN=220)="") as %String [ Language = objectscript, SQLProc = getRecordDefinition ]

getRecordDefinition - returns a JSON formatted Record Definition for a Unified Schema. The record definition is close to an AVRO Record Definition.

schemaName Name of the schema whose record definition is to be retrieved
namespace The namespace of the schema. If namespace is null or empty then schemaName is expected to be a fully qualified name.
return Return value is a JSON formatted record definition.

classmethod getSchema(schemaName As %String(MAXLEN=220), namespace As %String(MAXLEN=220)="") as %String [ Language = objectscript, SQLProc = getSchema ]

getSchema - returns a JSON formatted Unified Schema Definition.

schemaName Name of the schema to retrieve
namespace The namespace of the schema. If namespace is null or empty then schemaName is expected to be a fully qualified name.
return Return value is a JSON formatted schema definition.

classmethod getSchemaForClass(className As %String(MAXLEN=220)) [ Language = objectscript ]
classmethod getSchemas() as %String [ Language = objectscript, SQLProc = getSchemas ]

getSchemas - return a JSON array the names of schemas defined in the current namespace.

return Return value is a JSON formatted array of schema names.

classmethod isRuntimeUpToDate(schemaName As %String) as %Boolean [ Language = objectscript ]
classmethod isSchemaUpToDate(schemaName As %String, timestamp As %String) as %Boolean [ Language = objectscript ]
classmethod normalizeClassname(avroName As %String) as %Dictionary.Classname [ Language = objectscript ]
classmethod qualifyName(name As %String, namespace As %String = "") as %Dictionary.Classname [ Language = objectscript ]
classmethod uncompileSchema(schemaName As %String(MAXLEN=220), namespace As %String(MAXLEN=220)="") [ Language = objectscript, SQLProc = uncompileSchema ]

Uncompile the schema. If the schema originates from a client then the linked server implementation is deleted along with its extent. If the schema originates on the server then the linked server implementation is simply unlinked. This method throws an exception if any errors are encountered.

schemaName Name of the schema to uncompile
namespace The namespace of the schema. If namespace is null or empty then schemaName is expected to be a fully qualified name.

Indexes

index (IDKEY on ) [IdKey, Type = key];
Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()
index (kFN on fullname) [PrimaryKey, Type = key];
Index methods: kFNCheck(), kFNCheckUnique(), kFNDelete(), kFNExists(), kFNOpen(), kFNSQLCheckUnique(), kFNSQLExists(), kFNSQLFindPKeyByConstraint(), kFNSQLFindRowIDByConstraint()

Triggers

trigger deleteTrigger (BEFORE event DELETE);

Inherited Members

Inherited Methods

Storage

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID)
=
name
namespace

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"1")
=
class
generatedBy

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"fields")
=
fields

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"indices")
=
indices

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"namedTypes")
=
namedTypes

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"parameters")
=
parameters

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"recordMetadata")
=
recordMetadata

Storage Model: Storage (%FOI.Schema)

^IRIS.FOI.MD.1(ID,"schema")
=
schema
Feedback