Class Reference
%iKnow.Filters.Filter
Server:irisdocs1
Instance:IRISLATEST
User:UnknownUser
 
-
  [%SYS] >  [%iKnow] >  [Filters] >  [Filter]
Private  Storage

abstract class %iKnow.Filters.Filter extends %RegisteredObject

This is the base class for iKnow Filter objects, restricting the scope of an iKnow Query to a subset of all the sources in a domain through filter criteria based on the properties of a Source. These criteria are expressed through a number of Filter Parameters which should be passed as arguments to the %New method when instantiating a filter object. Typically, the first Filter Parameter is the Domain ID of the domain of which sources are to be filtered.

Filters have a String Representation so they can be passed around in non-object environments such as SQL and SOAP. Subclasses should therefore provide an unambiguous implementation for ToString, serializing its Filter Parameters so the string can be passed around and then deserialized through the RestoreFilterFromString method. See also CreateAsString and %iKnow.Filters.FilterWSAPI for handling filters in non-COS environments.

Subclasses should provide an implementation for (at least) BuildSourceFilter, building a bitstring with 1s for those Source IDs satisfying the filter criteria the filter class represents. In their %OnNew implementation, subclasses should make sure to set the DomainId property and call Initialize after setting all other properties specific to its implementation that influence the outcome of its ToString.

Filters can be cached so their calculated bitstrings can be reused (as long as they are still valid) across processes and time. Cache usage can be configured either by setting the $$$IKPENABLEFILTERCACHE domain parameter, or through a subclass explicitly enabling or disabling it when calling Initialize.

Sample Filter implementations include %iKnow.Filters.ExternalIdFilter, %iKnow.Filters.SentenceCountFilter and %iKnow.Filters.SimpleMetadataFilter

WARNING: When implementing a custom filter class, either make its properties read-only, or override the corresponding Set methods to call ChangeParams to reset the internal representations after property values change. When setting these updateable properties in the class' %OnNew method, use i% syntax to bypass these setters.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
16 62


Summary

Properties
DomainId FilterId FilteredSourceCount IsCached
Selectivity

Methods
%%OIDGet %AddToSaveSet %BindExport
%BuildObjectGraph %ClassIsLatestVersion %ClassName
%Close %ConstructClone %DispatchClassMethod
%DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty
%Extends %GetParameter %IncrementCount
%IsA %IsModified %New
%NormalizeObject %ObjectModified %OriginalNamespace
%PackageName %RemoveFromSaveSet %SerializeObject
%SetModified %ValidateObject BuildOccurrenceFilter
BuildTypedEntOccFilter BuildUniqueFilter CheckResultCache
CheckResultCacheSingle ClearCachedFilter ClearCachedFilters
CreateAsString CreateFromBitstring CreateGroupAsString
DomainIdSet FilteredSourceCountGet FromString
GetCRCOccurrenceFilter GetCRCUniqueFilter GetCcUniqueFilter
GetEntityOccurrenceFilter GetEntityUniqueFilter GetFilteredCcFrequency
GetFilteredCcSpread GetFilteredCrcFrequency GetFilteredCrcSpread
GetFilteredCrcUniqueCount GetFilteredEntityFrequency GetFilteredEntitySpread
GetFilteredEntityUniqueCount GetFilteredStemFrequency GetFilteredStemSpread
GetFirstFilteredSource GetLabel GetNextCRCOccurrenceFilterOffset
GetNextCRCUniqueFilterOffset GetNextCcUniqueFilterOffset GetNextEntityOccurrenceFilterOffset
GetNextEntityUniqueFilterOffset GetNextFilterOffset GetNextPathFilterOffset
GetNextSourceFilterOffset GetNextSrcId GetPathFilter
GetSecondaryFilter GetSourceFilter Initialize
Invalidate IsFiltered IsValid
MergeBits RestoreFilterFromId RestoreFilterFromString
SaveFilteredFrequency SaveFilteredSpread SelectivityGet
StoreResultCache StoreResultCacheSingle ToArray
ToBitstring ToString

Subclasses
%iKnow.DeepSee.MDXFilter
%iKnow.Filters.ContainsEntityFilter %iKnow.Filters.ContainsRelatedEntitiesFilter %iKnow.Filters.DictionaryItemMatchFilter
%iKnow.Filters.DictionaryMatchFilter %iKnow.Filters.DictionaryTermMatchFilter %iKnow.Filters.ExternalIdFilter
%iKnow.Filters.GroupFilter %iKnow.Filters.PathFilter
%iKnow.Filters.RandomFilter %iKnow.Filters.SentenceCountFilter %iKnow.Filters.SentenceFilter
%iKnow.Filters.SimpleMetadataFilter %iKnow.Filters.SourceIdFilter
%iKnow.Filters.SqlFilter

Properties

• property DomainId as %Integer [ Final ];
The domain ID this filter instance is targeting.
• property FilterId as %Integer [ ReadOnly ];
An internal identifier for this Filter instance.
• property FilterValidGlo as %String [ Private,ReadOnly ];
• property FilteredBitsGlo as %String [ Private,ReadOnly ];
• property FilteredCrcUniqueCount as %Integer [ Private,InitialExpression = -1,ReadOnly ];

The total number of distinct CRCs occurring in at least one of the sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

• property FilteredEntityUniqueCount as %Integer [ Private,InitialExpression = -1,ReadOnly ];

The total number of distinct entities occurring in at least one of the sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

• property FilteredFreqGlo as %String [ Private,ReadOnly ];
• property FilteredGlo as %String [ Private,ReadOnly ];
• property FilteredQParams as %String [ Private,ReadOnly ];
• property FilteredQRange as %String [ Private,ReadOnly ];
• property FilteredQResult as %String [ Private,ReadOnly ];
• property FilteredSourceCount as %Integer [ InitialExpression = -1,ReadOnly ];

The total number of sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

• property FilteredSpreadGlo as %String [ Private,ReadOnly ];
• property IsCached as %Integer [ Final,InitialExpression = -1,ReadOnly ];
Whether or not this filter instance is stored in the persistent cache.
• property IsCalculatedGlo as %String [ Private,ReadOnly ];
• property Selectivity as %Numeric [ InitialExpression = -1,ReadOnly ];

The ratio of sources satisfying this filter instances criteria to the total number of sources in this domain.

This property is used to choose the fastest access path in iKnow Query implementations.


Methods

• final method BuildOccurrenceFilter(type As %Integer = $$$IKFENTOCC) as %Status

Builds a filter on entOccIds, crcOccIds or pathIds, starting from the one on Source IDs.

• abstract private method BuildSourceFilter(maxOffset As %Integer) as %Status

This is the primary method that needs to be implemented by an actual %iKnow.Filters.Filter subclass to translate the abstract filter criteria the subclass addresses into a bitstring based on Source IDs. The subclass' implementation of this method should use SetSourceBits for this purpose, setting the requested bitstrings for each offset up to maxOffset.

• final method BuildTypedEntOccFilter(type As %Integer) as %Status

Builds a filter on entity occurrence IDs specifically in a concept or relation role, starting from the one on entity occurrence IDs.

• final method BuildUniqueFilter(type As %Integer) as %Status

Builds a filter on entUniIds or crcUniIds, starting from the one on Source IDs.

• private method ChangeParams() as %Status

This method should be called inside *Set methods of subclasses that allow their properties to be changed in the instances lifetime, to make sure it's properly re-initialized.

• method CheckResultCache(pQueryClass As %String, pQueryName As %String, pParams As %List, pPage As %Integer, pPageSize As %Integer, Output pIsCached, Output pResult) as %Status
pParams has empty positions for the pPage and pPageSize parameters Only use for queries without ByRef or Output parameters (except pResult) !!
• method CheckResultCacheSingle(pQueryClass As %String, pQueryName As %String, pParams As %List, Output pIsCached, Output pResult) as %Status
Same as CheckResultCache, but for single-result queries Only use for queries without ByRef or Output parameters !!
• final classmethod ClearCachedFilter(domainId As %Integer, filterId As %Integer) as %Status [ SQLProc = ]

Clears a specific filter from the persistent filter cache, if it exists.

• final classmethod ClearCachedFilters(domainId As %Integer) as %Status [ SQLProc = ]

Clears all filters from the persistent filter cache.

• final classmethod CreateAsString(createParams...) as %String [ SQLProc = ]

This class method is an access point to generate the string representation (as specified in ToString) for %iKnow.Filters.Filter classes, accessible from COS and SQL scenarios that cannot or prefer not to directly instantiate objects through COS.

When calling this method, you should supply the Filter Parameters as if calling the %New method of this particular Filter implementation.

For Web Service scenario's, use the corresponding method in %iKnow.Filters.FilterWSAPI.

• classmethod CreateFromBitstring(pDomainId As %Integer, ByRef pBitstring) as %iKnow.Filters.Filter
• final classmethod CreateGroupAsString(domainId As %Integer, groupLogic As %Integer = $$$GROUPFILTERAND, negated As %Boolean = 0, filters...) as %String [ SQLProc = ]

This class enables SQL users to create the string representation of a %iKnow.Filters.GroupFilter composed of multiple subfilters passed in using their respective string representations as the filters... parameter.

For Web Service scenario's, use the corresponding method in %iKnow.Filters.FilterWSAPI.

• method DomainIdSet(domainId As %Integer) as %Status
Override Set method to invalidate filter upon change
• method FilteredSourceCountGet() as %Integer
This is a Get accessor method for the FilteredSourceCount property.
• classmethod FromString(pDomainId As %String, pString As %String, Output pFilter As %iKnow.Filters.Filter) as %Status

Converts the supplied string pString into a %iKnow.Filters.Filter object. In addition to the normal RestoreFilterFromString functionality (which expects pString to be the output of a ToString call on a filter object), this method supports the following shorthands:

Note: while covering a majority of common filter operations, the shorthand syntax is meant to simplify exploration through the command-line and does not handle every possible combination of parameters. Application code should therefore always use regular filter constructor methods and the string representations produced by ToString (which this method also accepts).

• final method GetCRCOccurrenceFilter(offset As %Integer) as %String

Returns a bitstring on crcOccIDs, representing those CRC occurrences appearing in a source satisfying the filter criteria.

• final method GetCRCUniqueFilter(offset As %Integer) as %String

Returns a bitstring on crcUniIDs, representing those unique CRCs appearing in at least one source satisfying the filter criteria.

• final method GetCcUniqueFilter(offset As %Integer) as %String

Returns a bitstring on crcUniIDs, representing those unique CCs appearing in at least one source satisfying the filter criteria.

• final method GetEntityOccurrenceFilter(offset As %Integer) as %String

Returns a bitstring on entOccIDs, representing those entity occurrences appearing in a source source satisfying the filter criteria.

• final method GetEntityUniqueFilter(offset As %Integer) as %String

Returns a bitstring on entUniIDs, representing those unique entities appearing in at least one source satisfying the filter criteria.

• method GetFilteredCcFrequency(ccUniId As %Integer, type As %Integer = $$$IKFCCUNI) as %Integer

Returns the total frequency of a CC in the sources satisfying this filter instances criteria.

• method GetFilteredCcSpread(ccUniId As %Integer, type As %Integer = $$$IKFCCUNI) as %Integer

Returns the total number of sources satisfying this filter instances criteria in which the supplied CC appears.

• method GetFilteredCrcFrequency(crcUniId As %Integer) as %Integer

Returns the total frequency of a CRC in the sources satisfying this filter instances criteria.

• method GetFilteredCrcSpread(crcUniId As %Integer) as %Integer

Returns the total number of sources satisfying this filter instances criteria in which the supplied CRC appears.

• method GetFilteredCrcUniqueCount(ByRef approximate As %Boolean = 0) as %Integer

Returns the total number of distinct CRCs occurring in at least one of the sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

• method GetFilteredEntityFrequency(entUniId As %Integer, role As %Integer = $$$ENTTYPEANY) as %Integer

Returns the total frequency of an entity in the sources satisfying this filter instances criteria, where the entities role is concept (if role = $$$ENTTYPECONCEPT), relation (if role = $$$ENTTYPERELATION) or either of the two (if role = $$$ENTTYPEANY).

• method GetFilteredEntitySpread(entUniId As %Integer, role As %Integer = $$$ENTTYPEANY, details As %List = "") as %Integer

Returns the total number of sources in which the supplied entity appears that satisfy this filter instances criteria, where its role is concept (if role = $$$ENTTYPECONCEPT), relation (if role = $$$ENTTYPERELATION) or either of the two (if role = $$$ENTTYPEANY).

• final method GetFilteredEntityUniqueCount(ByRef approximate As %Boolean = 0) as %Integer

Returns the total number of distinct entities occurring in at least one of the sources satisfying this filter instances criteria.

This property is used to choose the fastest access path in iKnow Query implementations.

• method GetFilteredStemFrequency(pStemUniId As %Integer, pRole As %Integer = $$$ENTTYPEANY) as %Integer

Returns the total frequency of a stem in the sources satisfying this filter instances criteria, where the stem's role is concept (if pRole = $$$ENTTYPECONCEPT), relation (if pRole = $$$ENTTYPERELATION) or either of the two (if pRole = $$$ENTTYPEANY).

• method GetFilteredStemSpread(pStemUniId As %Integer, pRole As %Integer = $$$ENTTYPEANY, details As %List = "") as %Integer

Returns the total number of sources in which the supplied stem appears that satisfy this filter instances criteria, where its role is concept (if pRole = $$$ENTTYPECONCEPT), relation (if pRole = $$$ENTTYPERELATION) or either of the two (if pRole = $$$ENTTYPEANY).

• method GetFirstFilteredSource(direction As %Integer = 1) as %Integer

Returns the first Source ID satisfying this filter isntances criteria, starting from the lowest (direction 1) or highest Source ID (direction -1). Returns "" when no source is filtered.

• method GetLabel() as %String
Utility method to return a label for this filter instance. Custom filter classes may override this method to return a nicer label in client applications.
• final method GetNextCRCOccurrenceFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on CRC occurrence IDs.

• final method GetNextCRCUniqueFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on unique CRC IDs.

• final method GetNextCcUniqueFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on unique CC IDs.

• final method GetNextEntityOccurrenceFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on entity occurrence IDs.

• final method GetNextEntityUniqueFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on unique entity IDs.

• method GetNextFilterOffset(type As %Integer, offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer
• final method GetNextPathFilterOffset(offset As %Integer, Output nextBits As %String, direction As %Integer = 1) as %Integer

Returns the next offset for which this filter has bits (also returned as nextBits) in its filter on path IDs.

• method GetNextSourceFilterOffset(offset As %Integer = "", Output nextBits As %Integer, direction As %Integer = 1) as %Integer

Retrieves a bitstring representing the Source IDs satisfying this Filters criteria, for the offset (sourceId\64000+1) following the supplied one. The returned number is the next offset (given the direction).

• method GetNextSrcId(pSrcId As %Integer) as %Integer
• final method GetPathFilter(offset As %Integer) as %String

Returns a bitstring on path IDs, representing those paths appearing in a source satisfying the filter criteria.

• method GetSecondaryFilter(type As %Integer, offset As %Integer) as %String
• final method GetSourceFilter(offset As %Integer) as %String

Returns a bitstring representing the Source IDs satisfying this Filters criteria, for the given offset (sourceId\64000+1).

• method Initialize(useCache As %Integer = -1) as %Status

This method initializes the data structures this Filter object will be using througout its lifetime as an object instance. If caching is enabled for this object (useCache = 1), it will check if there is already a cached entry corresponding to these filter criteria it can reuse, or create a new cache entry otherwise. If caching is disabled (useCache = 0), Process-Private Globals will be used for storing this filter instances internals and nothing will be reused. If useCache = -1 (default), the domain default will be used (set through the $$$IKPENABLEFILTERCACHE domain parameter).

• method Invalidate(type As %Integer = $$$IKFSOURCE) as %Status

Resets all internal representations, forcing further use of this filter to recalculate results. If a type is supplied, only the bitstrings of that type are reset, including dependent ones. In the case of Source IDs (type = $$$IKFSOURCE), specific offset values can be invalidated separately.

• method IsFiltered(id As %Integer, type As %Integer = $$$IKFSOURCE) as %Boolean

Returns whether the id of the given type appears in any source satisfying this filter instances criteria.

• method IsValid(type As %Integer = $$$IKFSOURCE) as %Boolean

Checks if this filter for type is still up-to-date with regards to incorporating the most recent source additions and changes. Subclasses might wish to override this method but should combine their additional checks with the result of this root implementation if they do.

If the requested filter is not calculated, this method will return 0.

• method MergeBits(globName As %String, type As %Integer = $$$IKFSOURCE) as %Status

Merges this filter instances internal bitstring representation with the supplied global using AND logic.

• final classmethod RestoreFilterFromId(domainId As %Integer, filterId As %Integer) as %iKnow.Filters.Filter

Utility method to restore a cached filter based on its cached filter ID.

• final classmethod RestoreFilterFromString(filterSpec As %String) as %iKnow.Filters.Filter

Utility method to recreate a filter based on its string representation, which by default corresponds to the filter class name, a pipe character (|) and a filter-specific string containing all parameters required to recreate the string using the %New method. Subclasses should override RestoreFilterFromStringInternal if this default behavior is not sufficient.

This method is used primarily in SQL and Web Service scenarios, where the filter objects themselves cannot be passed in a SQL statement or SOAP request.

• private classmethod RestoreFilterFromStringInternal(filterParams As %String) as %iKnow.Filters.Filter

Default implementation, with the filterParams corresponding to all %New arguments. See also RestoreFilterFromString.

• method SaveFilteredFrequency(type As %Integer, id As %Integer, freq As %Integer) as %Status

Utility method to explicitly register the filtered frequency for an entity or CRC. Note that for stems, we use -type in order not to mix with the positive values ($$$IKFENTOCC, $$$IKFENTOCCC, $$$IKFENTOCCR) used for entities.

• method SaveFilteredSpread(type As %Integer, id As %Integer, spread As %Integer) as %Status

Utility method to explicitly register the filtered spread for an entity or CRC. Note that for stems, we use -type in order not to mix with the positive values ($$$IKFENTOCC, $$$IKFENTOCCC, $$$IKFENTOCCR) used for entities.

• method SelectivityGet() as %Numeric
This is a Get accessor method for the Selectivity property.
• private final method SetSourceBits(offset As %Integer, bits As %String) as %Status

Method to be called by the subclass' implementation of BuildSourceBits to register a bitstring of Source IDs at a particular offset.

• method StoreResultCache(pQueryClass As %String, pQueryName As %String, pParams As %List, pPage As %Integer, pPageSize As %Integer, ByRef pResult) as %Status
• method StoreResultCacheSingle(pQueryClass As %String, pQueryName As %String, pParams As %List, pResult) as %Status
• method ToArray(Output pArray, pType As %Integer = $$$IKFSOURCE) as %Status
• method ToBitstring(Output pArray, pType As %Integer = $$$IKFSOURCE) as %Status
• abstract method ToString() as %String

Subclasses should implement this method to build a string representation of the filter instance. It should start with the filter class name, followed by a pipe (|) character and then a string representation that can be interpreted by its RestoreFilterFromStringInternal implementation.

• private method Validate(type As %Integer = $$$IKFSOURCE, Output isValid As %Boolean = 0) as %Status

Checks whether this filter is in a valid state and all calculated bitstrings are up-to-date through a call to IsValid, the result of which is returned as isValid. If the bitstrings of the requested type are invalid, Invalidate is called.



Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.