TBOX - Data Access API User Guide
Purpose
sapi.m manages the TBox, schema-level metadata, describing attributes (their range, cardinality, type, documentation, aliases). It mirrors the structure of api.m (which manages ABox transaction data) but stages datoms (records) into %TBR instead of %ABR, and commits them via the same Stage → Transact pattern.
TBox Region
The TBox (Terminological Box) is stored in a dedicated YottaDB database region (tbox.dat) with journal file (tbox.mjl). All globals in this region share the TB* prefix.
The TBox contains the “schema” or the structural definitions of your knowledge base. It defines the hierarchy, the classes, and the properties. Think of it as the blueprint.
- Focus: Classes (Entity Types) and Properties (Attributes).
- Example: “Every Man is a Person” or “A Car must have Wheels”
- RDF Context: This corresponds to RDFS or OWL vocabulary (e.g.,
rdfs:Class,owl:ObjectProperty,rdfs:subClassOf).
| Global | Description |
|---|---|
^TBE | TBox term index — registers every TBox entity ever asserted. ^TBE(eid,1)="" marks the entity as live. Root node holds total term. Entity IDs are sequential integers allocated via ^TBEAVT("seq"). |
^TBD | Value dictionary and attribute range — forward index ^TBD(aid,valkey)=literal. Serves two roles: (1) maps a valkey back to its human-readable literal for display and resolution, and (2) defines the extent of all values ever registered for a given attribute’s data type — ^TBD(aid,*) is the full materialized domain of that attribute. e.g. ^TBD(1004,*) contains all 17 IMDb IDs ever asserted across all movie entities. Despite living in the TBox region, ^TBD is shared infrastructure — aid may be a TBox metadata attribute (e.g. sys.attr.cardinality) or an ABox domain attribute (e.g. sandbox.movie.title). |
^TBDR | Reverse value dictionary counter — ^TBDR(aid,literal)=valkey. Maps a literal to its allocated valkey (existence check / key resolution) and counts distinct domain values via the root node ^TBDR(aid)=n (e.g. ^TBDR(1004)=17 → 17 distinct IMDb IDs). Also holds ^TBDR(AKEYID,key)=valkey, resolving TBox natural-key labels to valkeys — used by GetEID^sapiGet/GetEID^apiGet |
^TBEAVT | TBox primary assertion store — ^TBEAVT(eid,aid,valkey,tx)=1. Records every schema metadata assertion. Subscript order supports entity-centric traversal. Root node holds total assertion count. ^TBEAVT("seq") holds the last allocated entity ID. |
^TBAVET | TBox inverted index — ^TBAVET(aid,valkey,eid,tx)=1. Supports lookup of entities by attribute value e.g. find all attributes with cardinality one, or resolve a unique attribute value to its entity. |
^TBKW | Keyword dictionary — ^TBKW(key,idx)=alias. Maps full schema keys and system commands to their short aliases loaded into process memory at startup via Load^keywords. Covers entity keys (obj.tom_hanks → TomHanks), attribute keys (sys.attr.key → key), enumerated values (sys.enum.cardinality.one → ONE), data types (sys.val.string → STRING), abstract types (sys.type.attr → ATYPE), and interactive shortcuts (DO PrintTBoxState^sapi → TBS). Multiple aliases per key are supported via the idx subscript. |
^TBEnts | Export structure — ^TBEnts(eid,ekey,akey)=val. Populated by ExportEntities^sapi for SQL access via YDB Octo. Holds a denormalized, human-readable snapshot of all entity attribute values under a given namespace. Cleared on each ExportEntities call. |
Disambiguation of Attribute Concepts
The datom model uses several related concepts that must be distinguished: Attribute Domain, Attribute Range, and Attribute Value Domain (Attribute Dictionary). Although they all describe constraints or possible values around an attribute, they operate at different levels:
- Attribute Domain defines the allowed source entity type (the subject of the datom).
- Attribute Range defines the allowed target type (the object of the datom), which may be a primitive value type, enumerated value type, composite value type, or another entity type.
- Attribute Value Domain / Attribute Dictionary defines the concrete values registered for an attribute and is materialized through the
^TBD/^TBDRbidirectional dictionary.
Attribute Dictionary and Value Resolution
Together ^TBD and ^TBDR form a bidirectional value dictionary. Every value registered for an attribute data type has both a forward entry (^TBD) and a reverse entry (^TBDR), allocated atomically. The pair also constitutes the materialized value domain of each attribute, querying ^TBD(aid,*) or ^TBDR(aid,*) gives the complete set of distinct values ever registered for that attribute across all entities, making range queries and value existence checks O(1) regardless of whether aid belongs to a TBox metadata attribute or an ABox data attribute.
Without this dictionary, the same check would require scanning the much larger assertion store instead; ^TBAEVT for TBox facts, ^AEVT for ABox facts.
Attribute Domain
The Attribute Domain defines the allowed source entity type of a datom.
Which entities are allowed to assert this attribute?
Example:
Movie ───────── sandbox.movie.imdbid ─────────> StringFor:
sandbox.movie.imdbidthe Attribute Domain is:
MovieMeaning only entities classified as Movie may assert sandbox.movie.imdbid.
Attribute Range
The Attribute Range defines the allowed target type of the datom. It answers:
Examples:
Primitive value:
sandbox.movie.imdbid
|
v
sys.val.stringReference value:
sandbox.person.favmovie
|
v
MovieThe range may therefore be:
- a primitive value type (
sys.val.string,sys.val.integer, etc.) or enumerated value type or composite value type - another entity type (
Movie,Person, etc.), i.e. reference type
Attribute Value Domain / Attribute Dictionary
The Attribute Value Domain (also called the Attribute Dictionary) is the materialized set of concrete values registered for an attribute.
Which actual values have been observed or registered for this attribute?
Example:
For:
sandbox.movie.imdbidthe Attribute Range is:
sys.val.stringThe Attribute Value Domain contains:
tt0011100
tt0976051
tt1570728
...Internally:
^TBD(1007,"K3EF.018866")="tt0011100"
^TBD(1007,"K3EF.01887E")="tt0976051"Together:
Attribute Domain
|
v
Movie
|
|
| sandbox.movie.imdbid
|
v
Attribute Range
|
v
sys.val.string
Attribute Value Domain / Dictionary
|
+--> tt0011100
+--> tt0976051
+--> tt1570728| Term | Meaning | Storage |
|---|---|---|
| Attribute Domain | Allowed subject entity type | sys.attr.domain (or equivalent) |
| Attribute Range | Allowed object type/value type | sys.attr.range |
| Attribute Value Domain | Registered concrete values | ^TBD(aid,valkey) |
| Attribute Dictionary | Implementation view of Attribute Value Domain | ^TBD/^TBDR |
This terminology also aligns naturally with graph/datoms terminology: domain = source, range = target, while the dictionary is a materialized lookup structure.
Initialization
Before any schema operation, a user session must be initialized:
INIT
DO Setup^logger("DEBUG",1,0)
DO INIT^sapi
DO Load^keywords
QUITInput Forms
TaxisDB represents transaction data with YottaDB local sparse multi-dimensional sorted associative arrays:
- Local — process-private and non-persistent.
- Sparse — only assigned nodes consume memory.
- Multi-dimensional — any number of subscripts.
- Sorted — subscripts are maintained in collation order.
- Associative — subscripts are keys (strings or numbers).
Transaction data is semantically an unordered set of datoms, all of which are added to the database at an atomic moment in time. TaxisDB provides two input forms for staging datoms, which can be freely combined before a single Transact commits them all atomically.
Form 1 — Record set: Stage + Transact
Stage one or more schema attribute definitions as a local array, then commit.
S Movie(1,key)="sandbox.movie.title"
S Movie(1,range)=STRING
S Movie(1,cardin)=ONE
S Movie(1,isa)=ATYPE
S Movie(1,doc)="The title of the movie @en"
S Movie(1,req)=1
S Movie(1,valid)="$$IsLangStr^utils"
S Movie(1,alias)="title"
S Movie(2,key)="sandbox.movie.genre"
S Movie(2,range)=STRING
S Movie(2,cardin)=MANY
S Movie(2,isa)=ATYPE
S Movie(2,doc)="The genre of the movie @en"
S Movie(2,alias)="genre"
S Movie(3,key)="sandbox.movie.releaseYear"
S Movie(3,range)=INT
S Movie(3,cardin)=ONE
S Movie(3,isa)=ATYPE
S Movie(3,doc)="The year the movie was released in theaters @en"
S Movie(3,valid)="$$IsInt^utils"
S Movie(3,alias)="ry"
S Movie(4,key)="sandbox.movie.imdbid"
S Movie(4,range)=STRING
S Movie(4,cardin)=ONE
S Movie(4,isa)=ATYPE
S Movie(4,doc)="IMDB unique identifier for the entity @en"
S Movie(4,unq)=UNQINSERT
S Movie(4,req)=1
S Movie(4,alias)="imdb"
D Stage^sapi(.Movie)
D Transact^sapikey,range,cardin,isaare required for a new attribute- Multiple records (
Attr(1,...),Attr(2,...)…) can be staged in one call Transactmust be called explicitly to commit
Required Metadata Attributes for New Attributes
A record creates a new attribute only if sys.attr.key does not already resolve to an existing entity. In that case:
sys.attr.keyandsys.attr.isaare always requiredsys.attr.rangeandsys.attr.cardinalityare additionally required
Once the attribute exists, the same record becomes a valid update (key+isa+range are no longer required — Stage resolves the existing eid and only validates the new fields supplied).
Updating an Existing Attribute
if sys.attr.key resolves to an existing eid, only the supplied metadata keys are validated and staged, no required-field check is enforced.
Form 2 — Single datom: AssertDatom / AD
Convenience wrapper, stages and commits a single metadata attribute assertion (datom) for an existing schema attribute. Mirrors AssertDatom^api in structure. This is only a shortcut method to update an existing attribute of the schema quickly. For bulk changes or new attributes use Stage^sapi with a 2D local array.
DO AssertDatom^sapi("sandbox.person.name","sys.attr.description","name of the person @en")
; or using keyword variables (aliases) for `sys.attr.title` and `sys.attr.description`
DO AssertDatom^sapi(title,doc,"Ο τίτλος της ταινίας @el")Form 3 — Single attribute creation: AddAttr
Convenience wrapper for creating a single schema attribute in one call. Builds a minimal YottaDB compatible (2D local array) metadata structure and delegates to Stage.
DO AddAttr^sapi("sandbox.person.name",STRING,ONE,ATYPE)
DO AddAttr^sapi("sandbox.person.age",INT,ONE,ATYPE)Parameters, in order: ekey, range, cardin, isa, with optional doc, alias, req, valid, ns, user trailing.
ekey,range,cardin,isaare required — the call silently no-ops if any is empty- Equivalent to building a one-record
Attrarray via Form 1 and callingStage^sapi - Unlike
AssertDatom^sapi,AddAttris for new attributes — it does not requireekeyto already exist
Validation Errors
- Unknown metadata key
- Empty value for a metadata key
- Invalid language-tagged string
All validation failures abort before Transact opens a transaction — %TBR remains empty, logged as Transact: %TBR is empty — nothing to commit.
Inspection & Reporting
These routines read schema metadata for inspection — they do not stage or commit any datoms.
PrintTBoxState / X TBS — overall schema status
DO PrintTBoxState^sapi
; or use
X TBSPrints a summary table: last transaction ID, total terms defined, total triplet facts, last entity ID allocated, total value keys, and per-namespace attribute value counts for sys.attr and sandbox namespaces.
YDB>X TBS
+________________________+________________________+________+
| Global Key | Description | Value |
+________________________+________________________+________+
| ^TX | Last Transaction | 7408 |
| ^TBE | Total terms defined | 60 |
+________________________+________________________+________+
| | | |
| Assertions | | |
+________________________+________________________+________+
| ^TBEAVT | Total triplet facts | 491 |
| ^TBEAVT("seq") | Last entity ID | 1008 |
+________________________+________________________+________+
| | | |
| Data Type Values | | |
+________________________+________________________+________+
| ^TBDR | Total value keys | 400 |
+________________________+________________________+________+
| | sys.attr | 24 |
+________________________+________________________+________+
| ^TBDR(10) | sys.attr.key | 62 |
| ^TBDR(40) | sys.attr.range | 10 |
| ^TBDR(41) | sys.attr.cardinality | 2 |
| ^TBDR(42) | sys.attr.unique | 2 |
| ^TBDR(44) | sys.attr.indexed | 0 |
| ^TBDR(62) | sys.attr.description | 62 |
| ^TBDR(68) | sys.attr.ensure | 0 |
| ^TBDR(69) | sys.attr.entattributes | 0 |
| ^TBDR(70) | sys.attr.entvalidation | 0 |
| ^TBDR(71) | sys.attr.validation | 4 |
| ^TBDR(205) | sys.attr.abbr | 1 |
| ^TBDR(210) | sys.attr.alias | 62 |
| ^TBDR(220) | sys.attr.required | 2 |
| ^TBDR(230) | sys.attr.usage | 20 |
| ^TBDR(240) | sys.attr.label | 55 |
| ^TBDR(250) | sys.attr.name | 52 |
| ^TBDR(260) | sys.attr.example | 13 |
| ^TBDR(267) | sys.attr.wikipage | 6 |
| ^TBDR(268) | sys.attr.homepage | 1 |
| ^TBDR(270) | sys.attr.extid.code | 23 |
| ^TBDR(277) | sys.attr.id | 0 |
| ^TBDR(280) | sys.attr.exptype | 2 |
| ^TBDR(290) | sys.attr.notes | 4 |
| ^TBDR(299) | sys.attr.isa | 8 |
+________________________+________________________+________+
| | sandbox | 8 |
+________________________+________________________+________+
| ^TBDR(1001) | sandbox.movie.title | 1 |
| ^TBDR(1002) | sandbox.movie.genre | 2 |
| ^TBDR(1003) | sandbox.movie.releaseY | 1 |
| ^TBDR(1004) | sandbox.movie.imdbid | 1 |
| ^TBDR(1005) | sandbox.dlc.id | 1 |
| ^TBDR(1006) | sandbox.dlc.checkup | 1 |
| ^TBDR(1007) | sandbox.dlc.count | 1 |
| ^TBDR(1008) | sandbox.dlc.txdate | 1 |
+________________________+________________________+________+PrintAttributes / PA — value counts for a namespace
Lists every attribute whose key matches the ns prefix, showing its attribute ID, key string, and how many distinct values have been registered for it.
Parameters
ns— namespace prefix used to filter attributes, e.g."sandbox","sandbox.movie","sys.attr"isSorted— (optional, default 1) if1, rows are sorted alphabetically by key. If0, rows are sorted by attribute ID.
; Sorted alphabetically by key (default)
DO PrintAttributes^sapi("sandbox.movie")
+______________+________________________________+________+
| | sandbox.movie | 5 |
+______________+________________________________+________+
| ^TBDR(1005) | sandbox.movie.genre | 8 |
| ^TBDR(1007) | sandbox.movie.imdbid | 17 |
| ^TBDR(1006) | sandbox.movie.releaseYear | 10 |
| ^TBDR(1004) | sandbox.movie.title | 15 |
| ^TBDR(1008) | sandbox.movie.tmdbid | 0 | ; Sorted by attribute ID
DO PrintAttributes^sapi("people.person",0)
+______________+________________________________+________+
| | people.person | 31 |
+______________+________________________________+________+
| ^TBDR(1013) | people.person | 0 |
| ^TBDR(1014) | people.person.name | 0 |
| ^TBDR(1015) | people.person.additionalName | 0 |
| ^TBDR(1016) | people.person.affiliation | 0 |
| ^TBDR(1017) | people.person.alumniOf | 0 |
| ^TBDR(1018) | people.person.birthDate | 0 | PrintEntities/PEs vs. PrintAttributes/PA
Use PrintAttributes when you want a quick summary of the attributes defined under a namespace: one row per attribute showing its eid, key, and value count. Use PrintEntities when you want the full picture of everything in a namespace, not just attributes, but any TBox entity, including atomic value types (sys.val.*), enumerated values (sys.enum.*), and abstract types (sys.type.*), with the complete set of metadata printed for each one. In short: PrintAttributes gives you a compact attribute index; PrintEntities gives you a detailed, entity-by-entity dump across the whole schema.
PrintSchema / PS — full schema table
Prints a formatted table with one row per matching attribute, showing eid, key, range, cardinality, required flag, uniqueness constraint, and description.
DO PrintSchema^sapi("sandbox.movie") | eid | akey | range | cardinality | required | unique | doc |
|---|---|---|---|---|---|---|
| 1001 | sandbox.movie.title | string | one | ✅ | The title of the movie | |
| 1002 | sandbox.movie.genre | string | many | The genre of the movie | ||
| 1003 | sandbox.movie.releaseYear | integer | one | The year the movie was released in theaters | ||
| 1004 | sandbox.movie.imdbid | string | one | ✅ | insert | IMDB unique identifier for the entity |
DO PrintSchema^sapi("sandbox.dlc")| eid | akey | range | cardinality | required | unique | doc |
|---|---|---|---|---|---|---|
| 1005 | sandbox.dlc.id | string | one | insert | Unique identifier for the inventory item | |
| 1006 | sandbox.dlc.checkup | string | one | Write notes for the checkup of the DLC item | ||
| 1007 | sandbox.dlc.count | integer | one | Current inventory count of the item | ||
| 1008 | sandbox.dlc.txdate | date | one | Date of the inventory transaction |
PrintEntity / PE — single TBox entity detail
Resolves a TBox entity and prints all its metadata assertions as a formatted table.
TBox entities are schema-level constructs:
- value types
- enumerated values
- attributes
- abstract types.
They are distinct from ABox entities (data-level instances managed by api.m) and are identified by sequential numeric eids allocated via ^TBEATV("seq").
; By natural key
DO PE^sapi("sandbox.movie.title")
DO PE^sapi("sys.attr.key")
DO PE^sapi("sys.val.string")
DO PE^sapi("sys.enum.cardinality.one")
DO PE^sapi("sys.type.attr")
; By numeric eid
DO PE^sapi(1001) ; sandbox.movie.title
DO PE^sapi(10) ; sys.attr.key
DO PE^sapi(23) ; sys.val.string
DO PE^sapi(35) ; sys.enum.cardinality.one
DO PE^sapi(200) ; sys.type.attr
; By alias
D PE^sapi(title) ; sandbox.movie.title
D PE^sapi(key) ; sys.attr.key
D PE^sapi(STRING) ; sys.val.string
D PE^sapi(ONE) ; sys.enum.cardinality.one
D PE^sapi(ATYPE) ; sys.type.attr======
sandbox.movie.title
======
1001 sys.attr.key sandbox.movie.title
1001 sys.attr.range sys.val.string
1001 sys.attr.cardinality sys.enum.cardinality.one
1001 sys.attr.description The title of the movie @en
1001 sys.attr.validation $$IsLangStr^utils
1001 sys.attr.alias title
1001 sys.attr.required 1
1001 sys.attr.isa sys.type.attr
======
sys.enum.cardinality.one
======
35 sys.attr.key sys.enum.cardinality.one
35 sys.attr.description A value representing a cardinality constraint used by `sys.attr.cardinality` to restrict an attribute to exactly one value. @en
35 sys.attr.alias ONE
35 sys.attr.label One @en
35 sys.attr.name one
35 sys.attr.extid.code :db.cardinality/one
35 sys.attr.isa sys.enum.cardinality
======
sys.val.string
======
23 sys.attr.key sys.val.string
23 sys.attr.description Value type representing textual data @en
23 sys.attr.alias STRING
23 sys.attr.label String Value Type @en
23 sys.attr.name string
23 sys.attr.extid.code :db.type/string
23 sys.attr.isa sys.type.val
======
sys.attr.key
======
10 sys.attr.key sys.attr.key
10 sys.attr.range sys.val.keyword
10 sys.attr.cardinality sys.enum.cardinality.one
10 sys.attr.unique sys.enum.unique.upsert
10 sys.attr.description A single-value attribute that assigns a unique, human-readable identifier to an object in its namespace @en
10 sys.attr.alias key
10 sys.attr.required 1
10 sys.attr.label Key @en
10 sys.attr.name key
10 sys.attr.extid.code :db/ident
10 sys.attr.isa sys.type.attrPrintEntities / PEs — all TBox entities in a namespace
Iterates every entity key under the ns prefix and calls PrintEntity for each.
Keys are read from ^TBDR(AKEYID,key) which is alphabetically ordered, iteration stops as soon as the prefix no longer matches.
Parameters
ns— namespace prefix to match against^TBDRkeyskeys— (optional, default 0) if1, print only each entity’ssys.attr.keyrow, one line per entity, with no headers, sorted alphabetically by key. Useful for a compact index of everything in a namespace.
; All system attributes
DO PEs^sapi("sys.attr")
; All enumerated values
DO PEs^sapi("sys.enum")
; All user-defined movie attributes
DO PEs^sapi("sandbox.movie")
; All entities under sys namespace (attributes, types, enums, value types)
DO PEs^sapi("sys")
; Compact key-only listing, sorted by key
DO PEs^sapi("sandbox.movie",1)Output — a PrintEntity block for each matching key:
YDB>DO PEs^sapi("sandbox.movie")
======
Namespace: sandbox.movie
======
======
sandbox.movie.genre
======
1002 sys.attr.key sandbox.movie.genre
1002 sys.attr.range sys.val.string
1002 sys.attr.cardinality sys.enum.cardinality.many
1002 sys.attr.description The genre of the movie @en
1002 sys.attr.alias genre
1002 sys.attr.isa sys.type.attr
======
sandbox.movie.imdbid
======
1004 sys.attr.key sandbox.movie.imdbid
1004 sys.attr.range sys.val.string
1004 sys.attr.cardinality sys.enum.cardinality.one
1004 sys.attr.unique sys.enum.unique.insert
1004 sys.attr.description IMDB unique identifier for the entity @en
1004 sys.attr.alias imdb
1004 sys.attr.required 1
1004 sys.attr.isa sys.type.attr
======
sandbox.movie.releaseYear
======
1003 sys.attr.key sandbox.movie.releaseYear
1003 sys.attr.range sys.val.integer
1003 sys.attr.cardinality sys.enum.cardinality.one
1003 sys.attr.description The year the movie was released in theaters @en
1003 sys.attr.validation $$IsInt^utils
1003 sys.attr.alias ry
1003 sys.attr.isa sys.type.attr
======
sandbox.movie.title
======
1001 sys.attr.key sandbox.movie.title
1001 sys.attr.range sys.val.string
1001 sys.attr.cardinality sys.enum.cardinality.one
1001 sys.attr.description The title of the movie @en
1001 sys.attr.validation $$IsLangStr^utils
1001 sys.attr.alias title
1001 sys.attr.required 1
1001 sys.attr.isa sys.type.attrWith keys=1, output is a compact one-line-per-entity index instead — no headers, no full attribute dump, just the sys.attr.key row, sorted alphabetically by key:
YDB>D PEs^sapi("sandbox.movie",1)
1005 sys.attr.key sandbox.movie.genre
1007 sys.attr.key sandbox.movie.imdbid
1006 sys.attr.key sandbox.movie.releaseYear
1004 sys.attr.key sandbox.movie.title
1008 sys.attr.key sandbox.movie.tmdbidExportEntities / EE — bulk export for SQL access via YDB Octo
Builds a normalized export structure in ^TBEnts(eid,ekey,akey)=val for every entity under ns. Used to populate the tbents table in YDB Octo for SQL queries. Clears ^TBEnts on each call. Defaults to "sys" if ns is omitted.
; Export all system entities
DO ExportEntities^sapi("sys")
; Export all user-defined movie attributes
DO ExportEntities^sapi("sandbox.movie")
; Export all sandbox entities
DO ExportEntities^sapi("sandbox")Output structure written to ^TBEnts:
PrintAttributeDictionary / PAD — print attribute dictionary
Resolves an attribute and prints the values registered in its dictionary (value domain).
The attribute argument can be supplied as either:
- a numeric attribute eid
- an attribute natural key (for example
sandbox.movie.imdbid)
Example:
YDB>D PR^sapi("sandbox.movie.imdbid")
======
sandbox.movie.imdbid
======
1007 K3EF.018866 tt0011100
1007 K3EF.01887E tt0976051
1007 K3EF.018882 tt1570728
1007 K3EF.018886 tt0177971
...or:
YDB>D PR^sapi(1007)
======
sandbox.movie.imdbid
======
1007 K3EF.018866 tt0011100
1007 K3EF.01887E tt0976051
1007 K3EF.018882 tt1570728
1007 K3EF.018886 tt0177971
...PrintAttributeDictionary displays the attribute dictionary values stored for the attribute.
The range of an attribute is defined by its sys.attr.range metadata assertion.
Example:
YDB>D PE^sapi("sandbox.movie.imdbid")
======
sandbox.movie.imdbid
======
1007 sys.attr.key sandbox.movie.imdbid
1007 sys.attr.range sys.val.string
1007 sys.attr.required 1
1007 sys.attr.cardinality sys.enum.cardinality.one
1007 sys.attr.unique sys.enum.unique.insert
1007 sys.attr.alias imdb
1007 sys.attr.description IMDB unique identifier for the entity
1007 sys.attr.isa sys.type.attrThe important metadata is:
sys.attr.range = sys.val.stringThis declares that the attribute values must conform to the value type sys.val.string.
The range defines the datatype of the attribute values:
Attribute:
sandbox.movie.imdbid
Range:
sys.val.string[!WARNING] It means every value asserted for sandbox.movie.imdbid must be a string.
The range does not store the actual values. The actual values are stored separately in the attribute value dictionary also known as attribute value domain:
^TBD(aid,valkey)For example:
^TBD(1007,"K3EF.018866")="tt0011100"
^TBD(1007,"K3EF.01887E")="tt0976051"
^TBD(1007,"K3EF.018882")="tt1570728"The relationship is:
Attribute
|
+-- sys.attr.range
| |
| v
| Value Type
| (sys.val.string)
|
+-- Domain Values
|
v
^TBD(attribute eid,value key)
(tt0011100, tt0976051, ...)“What type of values are valid?”
[! question] The attribute value dictionary/domain answers:
“Which concrete values exist or are allowed?”
For example:
sandbox.movie.imdbidhas:
Range:
sys.val.stringbecause IMDb identifiers are strings.
Its attribute dictionary contains:
tt0011100
tt0976051
tt1570728
...Each attribute dictionary value must satisfy the declared range.
Therefore:
"tt0011100"is valid because it is a string.
A numeric value:
12345would violate the attribute range.
Attributes may have a range without a finite dictionary/domain.
Example:
sandbox.movie.title
sys.attr.range = sys.val.stringThe range allows any string value, so there is no predefined list of dictionary members.
In contrast, enumerated attributes define a finite dictionary/domain:
sandbox.movie.status
sys.attr.range = sys.enum.movie.status
Dictionary:
released
production
cancelledHere the range identifies the value type, while the dictionary contains the permitted members.
PrintAttributeDictionary is therefore used to inspect the value domain side of an attribute: the concrete values associated with the attribute. The sys.attr.range metadata defines the value type that those values must satisfy.