Skip to main content

%iKnow.Queries.MetadataAPI

Class %iKnow.Queries.MetadataAPI Extends (%iKnow.Queries.MetadataI, %iKnow.Queries.AbstractAPI) [ Deprecated, System = 4 ]

The InterSystems IRIS NLP iKnow technology is now deprecated. Please see the product documentation for more detail.

This is the default implementation for the %iKnow.Queries.MetadataI interface and the central place to manage and query metadata fields and values.

Parameters​

GetFieldsRT​

Parameter GetFieldsRT = "mdFieldId:%String,fieldName:%String,supportedOperators:%List,dataType:%String,storage:%Integer,caseSensitive:%Boolean,lovId:%Integer,validateLov:%Boolean,hidden:%Boolean";

RemoveFieldEXP​

Parameter RemoveFieldEXP [ Internal ] = 1;

RemoveFieldByIdEXP​

Parameter RemoveFieldByIdEXP [ Internal ] = 1;

UpdateFieldEXP​

Parameter UpdateFieldEXP [ Internal ] = 1;

UpdateFieldByIdEXP​

Parameter UpdateFieldByIdEXP [ Internal ] = 1;

GetValuesRT​

Parameter GetValuesRT = "mdFieldId:%Integer,fieldName:%String,value:%String";

GetValuesByIdRT​

Parameter GetValuesByIdRT = "mdFieldId:%Integer,fieldName:%String,value:%String";

SetValueEXP​

Parameter SetValueEXP [ Internal ] = 1;

SetValueByIdEXP​

Parameter SetValueByIdEXP [ Internal ] = 1;

AddLovValueEXP​

Parameter AddLovValueEXP [ Internal ] = 1;

GetLovValuesRT​

Parameter GetLovValuesRT = "value:%String";

GetFieldValuesRT​

Parameter GetFieldValuesRT = "value:%String";

GetFieldValuesByIdRT​

Parameter GetFieldValuesByIdRT = "value:%String";

GetLovsRT​

Parameter GetLovsRT [ Deprecated ] = "lovId:%Integer,name:%String,autoExtend:%Boolean";

GetUniqueValuesRT​

Parameter GetUniqueValuesRT = "value:%String,frequency:%Integer";

GetUniqueValuesByIdRT​

Parameter GetUniqueValuesByIdRT = "value:%String,frequency:%Integer";

Methods​

GetFields​

ClassMethod GetFields(ByRef result As %Integer, domainId As %Integer, includeHidden As %Boolean = 0) As %Status

Returns all field definitions (including their properties) for the given domain.

Setting includeHidden to true will also return any metadata fields marked as 'hidden'.

GetFieldId​

ClassMethod GetFieldId(domainId As %Integer, fieldName As %String, Output sc As %Status) As %Integer

Returns the metadata field ID corresponding to the supplied name, or "" if none exists in this domain.

AddField​

ClassMethod AddField(domainId As %Integer, fieldName As %String, supportedOperators As %List = {$lb($$$MDOPEQUAL)}, dataType As %String = {$$$MDDTSTRING}, storage As %Integer = {$$$MDSTNORMAL}, caseSensitive As %Boolean = 0, lovId As %Integer = -1, validateLov As %Boolean = 1, hidden As %Boolean = 0, Output sc As %Status = {$$$OK}) As %Integer

Adds a field definition with the given name and properties.

  • The supportedOperators parameter specifies which operations (such as $$$MDOPEQUAL) will be available for filtering criteria
  • For dataType, choose either $$$MDDTSTRING, $$$MDDTNUMBER or $$$MDDTDATE ($horolog format)
  • Use storage to control how values are stored: $$$MDSTNORMAL for cases where you would use a normal index, $$$MDSTBITMAP where you would use a bitmap index (few different metadata values compared to total # of records)
  • If dataType is $$$MDDTSTRING, caseSensitive controls whether or not string values should be treated as case-sensitive.
  • The lovId and validateLov parameters define whether a List Of Values is available for this metadata field and whether input values should be verified against this list. See also AddListOfValues.
  • If hidden is set to true, the field will by default not appear in metadata field and value lists.

RemoveField​

ClassMethod RemoveField(domainId As %Integer, fieldName As %String) As %Status

Removes a metadata field (by name) from the domain, including all references by existing sources.

RemoveFieldById​

ClassMethod RemoveFieldById(domainId As %Integer, fieldId As %Integer) As %Status

Removes a metadata field (by ID) from the domain, including all references by existing sources.

UpdateField​

ClassMethod UpdateField(domainId As %Integer, fieldName As %String, supportedOperators As %List = "", storage As %Integer = -1, hidden As %Integer = -1, lovId As %Integer = -2, validateLov As %Integer = -1) As %Status

Updates the properties for a given metadata field (by name). See also AddField.

Specifying a "" for the supportedOperators will leave the current value for that property. Similarly, specifying -1 for storage, hidden and validateLov or -2 for lovId will leave their respective values unmodified. Setting lovId to -1 will unset the LOV for this field.

UpdateFieldById​

ClassMethod UpdateFieldById(domainId As %Integer, fieldId As %Integer, supportedOperators As %List = "", storage As %Integer = -1, hidden As %Integer = -1, lovId As %Integer = -2, validateLov As %Integer = -1) As %Status

Updates the properties for a given metadata field (by ID). See also AddField.

Specifying a "" for the supportedOperators will leave the current value for that property. Similarly, specifying -1 for storage, hidden and validateLov or -2 for lovId will leave their respective values unmodified. Setting lovId to -1 will unset the LOV for this field.

GetValue​

ClassMethod GetValue(domainId As %Integer, fieldName As %String, externalId As %String, Output sc As %Status) As %String

Returns the actual value for a given metadata field (by name) and source (by External ID).

GetValueById​

ClassMethod GetValueById(domainId As %Integer, fieldId As %Integer, srcId As %Integer, Output sc As %Status) As %String

Returns the actual value for a given metadata field (by ID) and source (by Source ID).

GetValues​

ClassMethod GetValues(ByRef result As %Integer, domainId As %Integer, externalId As %String, includeHidden As %Boolean = 0) As %Status

Returns the actual metadata values for the given source (by External ID).

Setting includeHidden to true will also return the values for hidden metadata fields.

GetValuesById​

ClassMethod GetValuesById(ByRef result As %Integer, domainId As %Integer, srcId As %Integer, includeHidden As %Boolean = 0) As %Status

Returns the actual metadata values for the given source (by Source ID).

Setting includeHidden to true will also return the values for hidden metadata fields.

SetValue​

ClassMethod SetValue(domainId As %Integer, fieldName As %String, externalId As %String, value As %String) As %Status

Sets (or replaces if it exists) the value for a given metadata field (by name) for a given source (by External ID).

Values for fields of type $$$MDDTSTRING are normalized and stripped of whitespace and control characters at the beginning and end of the string.

SetValueById​

ClassMethod SetValueById(domainId As %Integer, fieldId As %Integer, srcId As %Integer, value As %String) As %Status

Sets (or replaces if it exists) the value for a given metadata field (by ID) for a given source (by Source ID). Explicitly setting a value to "" (null/empty string) will erase the current value.

Values for fields of type $$$MDDTSTRING are normalized and stripped of whitespace and control characters at the beginning and end of the string.

SetValueByIdInternal​

ClassMethod SetValueByIdInternal(domainId As %Integer, fieldId As %Integer, srcId As %Integer, value As %String, skipExistingValueCheck As %Boolean = 0) As %Status [ Internal ]

Internal method to set a metadata value directly, without performing any existence checks.

StartBatch​

ClassMethod StartBatch(domainId As %Integer) As %Status

Starts a 'batch' during which metadata values can be set. Some setting operations and index recalculations are optimized for batch processing.

NOTE: It is currently up to the user to make sure no metadata values are read during the batch and no values exist already (as replacing a value involves reading it). Reading metadata field values during a batch is not guaranteed to return correct results.

EndBatch​

ClassMethod EndBatch(domainId As %Integer) As %Status

Ends a metadata batch. See StartBatch for more details.

AddListOfValues​

ClassMethod AddListOfValues(domainId As %Integer, lovName As %String, autoExtend As %Boolean = 1, Output sc As %Status) As %Integer [ Deprecated ]

Adds a List Of Values to the domain, which can then be used as a list of allowable values for one or more metadata fields.

AddLovValue​

ClassMethod AddLovValue(domainId As %Integer, lovId As %Integer, value As %String, ByRef rank As %Integer = -1) As %Status [ Deprecated ]

Adds a new value to an existing List Of Values

GetLovValues​

ClassMethod GetLovValues(ByRef result As %Integer, domainId As %Integer, lovId As %Integer) As %Status [ Deprecated ]

Returns all the allowed values for a given metadata LOV.

GetFieldValues​

ClassMethod GetFieldValues(ByRef result, domainId As %Integer, fieldName As %String, page As %Integer = 1, pageSize As %Integer = 10) As %Status

Returns all the distinct values currently in use for a given metadata field (by name). See also GetUniqueValues for a version returning the number of sources with this metadata value and sorting options.

GetFieldValuesById​

ClassMethod GetFieldValuesById(ByRef result, domainId As %Integer, mdFieldId As %Integer, page As %Integer = 1, pageSize As %Integer = 10) As %Status

Returns all the distinct values currently in use for a given metadata field (by ID).

DeNormalizeValue​

ClassMethod DeNormalizeValue(value As %String, mdfData As %List) As %String [ Internal ]

NormalizeValue​

ClassMethod NormalizeValue(value As %String, mdfData As %List, Output isTruncated As %Boolean) As %String [ Internal ]

GetLovs​

ClassMethod GetLovs(ByRef result, domainId As %Integer, page As %Integer = 1, pageSize As %Integer = 10) As %Status [ Deprecated ]

Returns all LOVs (List of Values) registered for this domain.

SortByField​

ClassMethod SortByField(ByRef pResult, pDomainId As %Integer, ByRef pSources, pSort As %String, pPage As %Integer = 1, pPageSize As %Integer = 10) As %Status [ Internal ]

Note: This implementation offers slight performance improvements over the default implementation in %iKnow.Queries.MetadataI and uses the datatype-aware normalized form of the metadata field value for sorting purposes.

Allows the results of %iKnow.Queries.SourceAPI queries to be re-sorted along a particular metadata field. pSort is expected to contain the name of the metadata field to sort by, optionally followed by a space and "ASC" (default) or "DESC". The string "ExternalId" is also accepted as a valid sort field and should be resolved through the GetExternalId method in %iKnow.Queries.SourceAPI, unless there is a metadata field carrying the same name.

pSources is expected to be an array containing all (unsorted) query results with the source ID as the first row element, while pResult will be populated with the sorted results like a usual iKnow API query.

pSort can optionally be suffixed with a space and the string "ADDCOL", in which case, a column containing the actual metadata value is appended to the results. Use this feature with caution as it might impact SQL/WS clients, because the extra column is not declared in the original query specs.

Note: sources for which the requested metadata field is not populated or where its value is longer than $$$IKHASHSIZE (150 characters) will be left out of the results.

GetUniValue​

ClassMethod GetUniValue(pDomainId As %Integer, pUniValueId As %Integer) As %String

Returns the unique metadata value corresponding to the supplied pUniValueId.

GetUniValueId​

ClassMethod GetUniValueId(pDomainId As %Integer, pValue As %String, Output pSC As %Status = {$$$OK}) As %Integer [ Internal ]

Returns the id of a unique metadata value (for use in compressed storage) or creates it if it didn't exist yet.

Note: This method is intended for internal use only.

GetUniqueValues​

ClassMethod GetUniqueValues(ByRef pResult, pDomainId As %Integer, pFieldName As %String, pPage As %Integer = 1, pPageSize As %Integer = 10, pFilter As %iKnow.Filters.Filter = "", pSortType As %String = "") As %Status

Returns all the unique metadata values for field pFieldName in sources satisfying the supplied filter, optionally sorted by value (pSortType = "VALUE") or frequency (pSortType = "FREQUENCY"). The returned frequency represents the number of sources with this metadata value (satisfying the filter).

NOTE: sorting by value is only precise up to the 150 first characters

GetUniqueValuesById​

ClassMethod GetUniqueValuesById(ByRef pResult, pDomainId As %Integer, pFieldId As %Integer, pPage As %Integer = 1, pPageSize As %Integer = 10, pFilter As %iKnow.Filters.Filter = "", pSortType As %String = "") As %Status

Returns all the unique metadata values for field pFieldId in sources satisfying the supplied filter, optionally sorted by value (pSortType = "VALUE") or frequency (pSortType = "FREQUENCY"). The returned frequency represents the number of sources with this metadata value (satisfying the filter).

NOTE: sorting by value is only precise up to the 150 first characters

GetUniqueValueCount​

ClassMethod GetUniqueValueCount(pDomainId As %Integer, pFieldName As %String, pFilter As %iKnow.Filters.Filter = "", Output pSC = {$$$OK}) As %Integer

Returns the number of unique metadata values for a given field pFieldName in the sources satisfying the supplied filter, after normalization based on the field specifications such as case sensitivity and data type.

GetUniqueValueCountById​

ClassMethod GetUniqueValueCountById(pDomainId As %Integer, pFieldId As %Integer, pFilter As %iKnow.Filters.Filter = "", Output pSC As %Status = {$$$OK}) As %Status

Returns the number of unique metadata values for a given field pFieldId in the sources satisfying the supplied filter, after normalization based on the field specifications such as case sensitivity and data type.

GetMetaSpreadByEntities​

ClassMethod GetMetaSpreadByEntities(pDomainId As %Integer, pFieldName As %String, pEntityList As %List, pFilter As %iKnow.Filters.Filter = "", pSetOp As %Integer = {$$$UNION}, Output pSC As %Status = {$$$OK}) As %Integer

Returns the "spread" of metadata values (number of distinct values) for field pFieldName for the entities in pEntityList, in the sources satisfying pFilter. When specifying multiple entities, sources (and their metadata values) are included based on the value of pSetOp: if pSetOp = $$$UNION, only one entity has to be present (default), if pSetOp = $$$INTERSECT, all of them need to be present.

GetMetaSpreadByEntityIds​

ClassMethod GetMetaSpreadByEntityIds(pDomainId As %Integer, pFieldName As %String, pEntityIdList As %List, pFilter As %iKnow.Filters.Filter = "", pSetOp As %Integer = {$$$UNION}, Output pSC As %Status = {$$$OK}) As %Integer

Returns the "spread" of metadata values (number of distinct values) for field pFieldName for the entities in pEntityIdList, in the sources satisfying pFilter. When specifying multiple entities, sources (and their metadata values) are included based on the value of pSetOp: if pSetOp = $$$UNION, only one entity has to be present (default), if pSetOp = $$$INTERSECT, all of them need to be present.

GetMetaSpreadInternal​

ClassMethod GetMetaSpreadInternal(pDomainId As %Integer, pFieldId As %Integer, pType As %String = "ENTITY", ByRef pIds, pFilter As %iKnow.Filters.Filter = "", pSetOp As %Integer = {$$$UNION}, Output pSC As %Status = {$$$OK}) As %Integer

CreateFilter​

ClassMethod CreateFilter(pDomainId As %Integer, pFieldName As %String, pOperator As %String, pValue As %String, Output pSC As %Status = {$$$OK}) As %iKnow.Filters.Filter

Create a %iKnow.Filters.Filter instance that filters sources according to the given criteria, using the filter class compatible with this %iKnow.Queries.MetadataI implementation.

For the default MetadataAPI, this is a %iKnow.Filters.SimpleMetadataFilter instance.

GetFieldInfo​

ClassMethod GetFieldInfo(pDomainId As %Integer, pFieldName As %String, Output pInfo) As %Status

Returns some basic facts about metadata field pFieldName

GetFieldInfoById​

ClassMethod GetFieldInfoById(pDomainId As %Integer, pFieldId As %String, Output pInfo) As %Status

Returns some basic facts about metadata field with ID pFieldId

PopulateFromSQL​

ClassMethod PopulateFromSQL(pDomainId As %Integer, pSQL As %String, pIgnoreErrors As %Boolean = 1) As %Status

Populates any number of metadata fields with the values retrieved based on the values retrieved by a query pSQL. The query should at least return a column named "SourceId" containing iKnow Source IDs or a column named "ExternalId" containing the full External IDs of the sources whose metadata fields are to be updated. All other columns with names matching existing metadata fields for this domain will be used to update or set the fields' values for each record. Columns whose name does not correspond to an existing metadata field will be ignored.

Sample query:

SELECT ':SQL:' || YEAR(EventDate) || ':' || EventId As ExternalId, InjuriesHighest, YEAR(EventDate) "Year" FROM Aviation.Event

This will update the InjuriesHighest and Year fields (if they exist).