This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Demo.CustomSearchTable.Sample

persistent class Demo.CustomSearchTable.Sample extends Ens.CustomSearchTable

SQL Table Name: Demo_CustomSearchTable.Sample

This is a sample CustomSearchTable to demonstrate the some of the primary features of custom search tables by showing possible indexing strategies for the Ens.StreamContainer class.
The SearchTable implements a multi-index approach to indexing the first 12 characters of the target Stream property using bitmap indices on %FirstFour, %SecondFour and %ThirdFour. The underlying properties start with the "%" character so they are not directly exposed to users as options - instead, the Stream12 virtual property is listed as an indexed property in GetVirtualPropertyList()(), so users can search on the first 12 characters. The actual search implementation is in the OnProcessCondition()() callback so that the indices are used by the SQL engine.
The Stream250Early and Stream250Late virtual properties demonstrate the two options available for retrieving and displaying the first 250 characters of the stream without needing to index the contents of the stream. The Stream250Early property is fetched "Early" because it is fetched using an SQL stored procedure during the SQL processing of results and any conditions on the property are applied by the SQL engine. The Stream250Late property is fetched "Late" because it is fetched using a COS callback after the SQL engine has constructed a result set, so any conditions are applied as the COS code iterates over the results produced using standard SQL. Both properties are listed as non-indexed virtual properties in GetVirtualPropertyList()(), and the code to actually fetch the values is implemented in GetVirtualProperty()().

Property Inventory

Method Inventory

Parameters

parameter DOCCLASS = Ens.StreamContainer;
This class is intended to index Ens.StreamContainer messages. The EnsLib.File.PassthroughService and EnsLib.FTP.PassthroughService services send these messages, so you can experiment by indexing messages as sent by these services.

Properties

property %FirstFour as %String (MAXLEN = 4);
%FirstFour is intended to capture the first four characters of the StreamContainer's Stream contents. The property demonstrates how properties which start with "%" are not displayed to the user, but may be used when constructing queries. The four character restriction is imposed to allow the First bitmap index to be created on only these characters.
Property methods: %FirstFourDisplayToLogical(), %FirstFourGet(), %FirstFourGetStored(), %FirstFourIsValid(), %FirstFourLogicalToDisplay(), %FirstFourLogicalToOdbc(), %FirstFourNormalize(), %FirstFourSet()
property %SecondFour as %String (MAXLEN = 4);
%SecondFour is intended to capture the second four characters of the StreamContainer's Stream contents. The property demonstrates how properties which start with "%" are not displayed to the user, but may be used when constructing queries. The four character restriction is imposed to allow the Second bitmap index to be created on only these characters.
Property methods: %SecondFourDisplayToLogical(), %SecondFourGet(), %SecondFourGetStored(), %SecondFourIsValid(), %SecondFourLogicalToDisplay(), %SecondFourLogicalToOdbc(), %SecondFourNormalize(), %SecondFourSet()
property %ThirdFour as %String (MAXLEN = 4);
%ThirdFour is intended to capture the third four characters of the StreamContainer's Stream contents. The property demonstrates how properties which start with "%" are not displayed to the user, but may be used when constructing queries. The four character restriction is imposed to allow the Third bitmap index to be created on only these characters.
Property methods: %ThirdFourDisplayToLogical(), %ThirdFourGet(), %ThirdFourGetStored(), %ThirdFourIsValid(), %ThirdFourLogicalToDisplay(), %ThirdFourLogicalToOdbc(), %ThirdFourNormalize(), %ThirdFourSet()
property OrigFilename as %String;
OrigFilename is stored as a non-indexed property of the SearchTable class. This is somewhat redundant, but means that SQL operations which display this value don't need to load data from the original data location when the SearchTable is used to perform comparisons in a query.
Property methods: OrigFilenameDisplayToLogical(), OrigFilenameGet(), OrigFilenameGetStored(), OrigFilenameIsValid(), OrigFilenameLogicalToDisplay(), OrigFilenameLogicalToOdbc(), OrigFilenameNormalize(), OrigFilenameSet()
property Type as %String (COLLATION = "EXACT");
Type describes the type of stream referenced in the Stream property of the StreamContainer. It is a short text code, so lends itself to creating a bitmap index -- see the Type for details. The property is also declared with EXACT collation to ensure that any character-based matches are peformed using exact matching and NOT the default of uppercase matching.
Property methods: TypeDisplayToLogical(), TypeGet(), TypeGetStored(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToOdbc(), TypeNormalize(), TypeSet()

Methods

classmethod GetVirtualProperties(pDocID As %String, pPropNames As %List, Output pPropValues As %List) as %Status
Override of the base implementation of GetVirtualProperties(). We only load the target Ens.StreamContainer object once when retrieving multiple values for the instance.
classmethod GetVirtualProperty(pDocID As %String, pPropName As %String, Output pPropValue As %String, ByRef pUserArgs) as %Status
API to retrieve a named virtual property for a given document ID. If a virtual property is specified in GetVirtualPropertyList()(), this method should be updated to implement retrieval code for the property. Note that if GetVirtualProperties()() is overridden, this method may not be called for value retrieval.
classmethod GetVirtualPropertyList(Output pIndexedVirtualProperties As %List, Output pVirtualProperties As %List) as %Status
We provide a number of virtual properties in this class. Stream12 is a virtual property which represents the first 12 characters of the stream, which are indexed. Stream250Early and Stream250Late both represent the first 250 characters of the stream which are not indexed. Stream250Early is a virtual property which is fetched via a stored procedure during SQL execution, while Stream250Late is a virtual property which is fetched via the GetVirtualProperties()() API. StreamType is a virtual property which represents the actual stream type and is fetched via the GetVirtualProperties() API. For both of the last two properties, code is needed in OnProcessCondition()() to indicate that the property should not be fetched via SQL.
classmethod OnIndexDoc(pDocObj As Ens.StreamContainer, pSearchTable As Demo.CustomSearchTable.Sample) as %Status
Callback which should be implemented by users to populate the CustomSearchTable supplied in Ens.CustomSearchTable based on pDocObj. Note that the DocId property is prepopulated, so doesn't need to be reset. If the user doesn't want a particular CustomSearchTable instance to be saved, the user can set pSearchTable to the empty string (i.e. "") to prevent the indexing framework from saving an entry to disk.
classmethod OnProcessCondition(pProperty As %String, pOperator As %String, pValue As %String, pTableName As %String, pTableInFrom As %Boolean, pSelectAsName As %String, pDisplayOnly As %Boolean = 0, ByRef pSelect As %String, ByRef pFrom As %String, ByRef pWhere As %String, ByRef pSQLFetch As %Boolean) as %Status
Callback invoked by the Message Viewer UI whenever a condition for a CustomSearchTable is selected. pProperty specifies the property name to be retrieved. Note: pProperty may be the empty string when adding a SearchTable for the first time. Ensure that the code in this method handles this case. pDisplayOnly indicates whether the user has selected the property as a display-only field. If pDisplayOnly is true, the values for the value and operator supplied in pValue and pOperator, respectively, should be ignored and no conditions should be added to the WHERE clause. If pDisplayOnly is false, users should make use of the GetSQLCondition() API in EnsPortal.MsgFilter.Assistant to produce valid SQL WHERE conditions based on the supplied arguments. pTableName specifies the name of the table to use in the FROM clause, and pTableInFrom indicates whether the table is already present in the FROM clause. pSelectAsName is the alias which should be used for the column in the eventual resultset. The pSelect, pFrom and pWhere arguments are strings which determine which subclauses (if any) should be added to the corresponding sections of the overall SQL query, and can be modified as needed while in this callback. The pSQLFetch flag indicates whether the value will be completely fetched by the supplied SQL terms. By default, ALL virtual properties will only be retrieved using ObjectScript AFTER the main SQL results have been produced. The purpose of this is to allow the post-SQL filter code to load all encountered virtual properties using the GetVirtualProperties()() API. Users should override this behaviour when indices are available in this class to improve the fetch performance of the generated query. In a similar vein, users may want to delay retrieval of non-indexed standard properties until after the SQL phase is complete, though this is not necessarily more efficient.

Indexes

index ($Sample on ) [Extent, Type = bitmap];
index (First on %FirstFour) [Type = bitmap];
This is a bitmap index on the first four characters of the stream's contents. It is intended to be used in conjunction with the Second and Third indices to find the first 12 characters of stream contents very efficiently. The eventual goal is to use a virtual property which relies on these indices to construct rapid searches on the underlying data without needing expensive reads of the entire stream from disk.
index (IDKEY on ) [IdKey, Type = key];
Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()
index (Second on %SecondFour) [Type = bitmap];
This is a bitmap index on the second four characters of the stream's contents. It is intended to be used in conjunction with the First and Third indices to find the first 12 characters of stream contents very efficiently. The eventual goal is to use a virtual property which relies on these indices to construct rapid searches on the underlying data without needing expensive reads of the entire stream from disk.
index (Third on %ThirdFour) [Type = bitmap];
This is a bitmap index on the third four characters of the stream's contents. It is intended to be used in conjunction with the First and Second indices to find the first 12 characters of stream contents very efficiently. The eventual goal is to use a virtual property which relies on these indices to construct rapid searches on the underlying data without needing expensive reads of the entire stream from disk.
index (Type on Type) [Type = bitmap];
The Type index is declared as a bitmap index as the Type property contains a short character code, so it is very efficient to match on specific values for this field.
Index methods: TypeDisplayToLogical(), TypeGet(), TypeGetStored(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToOdbc(), TypeNormalize(), TypeSet()

Inherited Members

Inherited Properties

Inherited Methods

Storage

Gray indicates storage defined by superclasses.

Storage Model: CacheStorage (Demo.CustomSearchTable.Sample)

^Demo.CustomSearchTable.SampleD(ID)
=
%%CLASSNAME
DocId
OrigFilename
Type
%FirstFour
%SecondFour
%ThirdFour
Feedback