Version: 5.3.3-ice35-b63

OmeroBlitz API
Home Previous Up Next Index

omero::api::Search

Overview

[ "ami", "amd" ] interface Search extends StatefulServiceInterface

Central search interface, allowing Web2.0 style queries. Each Search instance keeps up with several queries and lazily-loads the results as hasNext, next and results are called. These queries are created by the by* methods. Each instance also has a number of settings which can all be changed from their defaults via accessors, e.g. setBatchSize or setCaseSentivice. The only methods which are required for the proper functioning of a Search instance are:

Use of the allTypes method is discouraged, since it is possibly very resource intensive, which is why any attempt to receive results without specifically setting types or allowing all is prohibited.

See Also

IQuery

Operation Index

activeQueries
Returns the number of active queries.
setBatchSize
Sets the maximum number of results that will be returned by one call to results.
getBatchSize
Returns the current batch size.
setMergedBatches
Set whether or not results from two separate queries can be returned in the same call to results.
isMergedBatches
Returns the current merged-batches setting.
setCaseSentivice
Sets the case sensitivity on all queries where case-sensitivity is supported.
isCaseSensitive
Returns the current case sensitivity setting.
setUseProjections
Determines if Lucene queries should not hit the database.
isUseProjections
Returns the current use-projection setting.
setReturnUnloaded
Determines if all results should be returned as unloaded objects.
isReturnUnloaded
Returns the current return-unloaded setting.
setAllowLeadingWildcard
Permits full-text queries with a leading query if true.
isAllowLeadingWildcard
Returns the current leading-wildcard setting.
onlyType
Restricts the search to a single type.
onlyTypes
Restricts searches to a set of types.
allTypes
Permits all types to be returned.
onlyIds
Restricts the set of ids which will be checked.
onlyOwnedBy
Uses the model::Details::getOwner and model::Details::getGroup information to restrict the entities which will be returned.
notOwnedBy
Uses the model::Details::getOwner and model::Details::getGroup information to restrict the entities which will be returned.
onlyCreatedBetween
Restricts the time between which an entity may have been created.
onlyModifiedBetween
Restricts the time between which an entity may have last been modified.
onlyAnnotatedBetween
Restricts entities by the time in which any annotation (which matches the other filters) was added them.
onlyAnnotatedBy
Restricts entities by who has annotated them with an model::Annotation matching the other filters.
notAnnotatedBy
Restricts entities by who has not annotated them with an model::Annotation matching the other filters.
onlyAnnotatedWith
Restricts entities to having an model::Annotation of all the given types.
addOrderByAsc
A path from the target entity which will be added to the current stack of order statements applied to the query.
addOrderByDesc
A path from the target entity which will be added to the current stack of order statements applied to the query.
unordered
Removes the current stack of order statements.
fetchAnnotations
Queries the database for all model::Annotation annotations of the given types for all returned instances.
fetchAlso
Adds a fetch clause for loading non-annotation fields of returned entities.
resetDefaults
Resets all settings (non-query state) to the original default values, as if the instance had just be created.
byGroupForTags
Returns transient (without ID) model::TagAnnotation instances which represent all the model::TagAnnotation tags in the given group.
byTagForGroups
Creates a query which will return transient (without ID) model::TagAnnotation instances which represent all the model::TagAnnotation tag groups which the given tag belongs to.
byFullText
Passes the query as is to the Lucene backend.
byLuceneQueryBuilder
Builds a Lucene query and passes it to the Lucene backend.
bySimilarTerms
Returns transient (without ID) model::TextAnnotation instances which represent terms which are similar to the given terms.
byHqlQuery
Delegates to IQuery::findAllByQuery method to take advantage of the and, or, and not methods, or queue-semantics.
bySomeMustNone
Builds a Lucene query and passes it to byFullText.
byAnnotatedWith
Finds entities annotated with an model::Annotation similar to the example.
clearQueries
Removes all active queries (leaving resetDefaults settings alone), such that activeQueries will return 0.
and
Applies the next by* method to the previous by* method, so that a call hasNext, next, or results sees only the intersection of the two calls.
or
Applies the next by* method to the previous by* method, so that a call hasNext, next or results sees only the union of the two calls.
not
Applies the next by* method to the previous by* method, so that a call hasNext, next, or results sees only the intersection of the two calls.
hasNext
Returns true if another call to next is valid.
next
Returns the next entity from the current query.
results
Returns up to getBatchSize batch size number of results along with the related query metadata.
currentMetadata
Provides access to the extra query information (for example Lucene score and boost values) for a single call to next.
currentMetadataList
Provides access to the extra query information (for example Lucene score and boost values) for a single call to results.
remove
Unsupported operation.

Operations

int activeQueries() throws ServerError

Returns the number of active queries. This means that activeQueries gives the minimum number of remaining calls to results when batches are not merged.

Return Value

number of active queries

void setBatchSize(int size) throws ServerError

Sets the maximum number of results that will be returned by one call to results. If batches are not merged, then results may often be less than the batch size. If batches are merged, then only the last call to results can be less than batch size. Note: some query types may not support batching at the query level, and all instances must then be loaded into memory simultaneously.

Parameters

size
maximum number of results per call to results

int getBatchSize() throws ServerError

Returns the current batch size. If setBatchSize has not been called, the default value will be in effect.

Return Value

maximum number of results per call to results

void setMergedBatches(bool merge) throws ServerError

Set whether or not results from two separate queries can be returned in the same call to results.

bool isMergedBatches() throws ServerError

Returns the current merged-batches setting. If setMergedBatches has not been called, the default value will be in effect.

void setCaseSentivice(bool caseSensitive) throws ServerError

Sets the case sensitivity on all queries where case-sensitivity is supported.

bool isCaseSensitive() throws ServerError

Returns the current case sensitivity setting. If setCaseSentivice has not been called, the default value will be in effect.

void setUseProjections(bool useProjections) throws ServerError

Determines if Lucene queries should not hit the database. Instead all values which are stored in the index will be loaded into the object, which includes the id. However, the entity will not be marked unloaded and therefore it is especially important to not allow a projection-instance to be saved back to the server. This can result in DATA LOSS.

bool isUseProjections() throws ServerError

Returns the current use-projection setting. If true, the client must be careful with all results that are returned. See setUseProjections for more. If setUseProjections has not been called, the default value will be in effect.

void setReturnUnloaded(bool returnUnloaded) throws ServerError

Determines if all results should be returned as unloaded objects. This is particularly useful for creating lists for further querying via IQuery. This value overrides the setUseProjections setting.

bool isReturnUnloaded() throws ServerError

Returns the current return-unloaded setting. If true, all returned entities will be unloaded. If setReturnUnloaded has not been called, the default value will be in effect.

void setAllowLeadingWildcard(bool allowLeadingWildcard) throws ServerError

Permits full-text queries with a leading query if true.

See Also

isAllowLeadingWildcard
byFullText
bySomeMustNone

bool isAllowLeadingWildcard() throws ServerError

Returns the current leading-wildcard setting. If false, byFullText and bySomeMustNone will throw an ApiUsageException, since leading-wildcard searches are quite slow. Use setAllowLeadingWildcard in order to permit this usage.

void onlyType(string klass) throws ServerError

Restricts the search to a single type. All return values will match this type.

void onlyTypes(StringSet classes) throws ServerError

Restricts searches to a set of types. The entities returned are guaranteed to be one of these types.

void allTypes() throws ServerError

Permits all types to be returned. For some types of queries, this carries a performance penalty as every database table must be hit.

void onlyIds(sys::LongList ids) throws ServerError

Restricts the set of ids which will be checked. This is useful for testing one of the given restrictions on a reduced set of objects.

Parameters

ids
Can be null, in which case the previous restriction is removed.

void onlyOwnedBy(model::Details d) throws ServerError

Uses the model::Details::getOwner and model::Details::getGroup information to restrict the entities which will be returned. If both are non-null, the two restrictions are joined by an AND.

Parameters

d
Can be null, in which case the previous restriction is removed.

void notOwnedBy(model::Details d) throws ServerError

Uses the model::Details::getOwner and model::Details::getGroup information to restrict the entities which will be returned. If both are non-null, the two restrictions are joined by an AND.

Parameters

d
Can be null, in which case the previous restriction is removed.

void onlyCreatedBetween(RTime start, RTime stop) throws ServerError

Restricts the time between which an entity may have been created.

Parameters

start
Can be null, i.e. interval open to negative infinity.
stop
Can be null, i.e. interval opens to positive infinity.

void onlyModifiedBetween(RTime start, RTime stop) throws ServerError

Restricts the time between which an entity may have last been modified.

Parameters

start
Can be null, i.e. interval open to negative infinity.
stop
Can be null, i.e. interval open to positive infinity.

void onlyAnnotatedBetween(RTime start, RTime stop) throws ServerError

Restricts entities by the time in which any annotation (which matches the other filters) was added them. This matches the model::Details::getCreationEvent creation event of the omero::::model::Annotation.

Parameters

start
Can be null, i.e. interval open to negative infinity.
stop
Can be null, i.e. interval open to positive infinity.

void onlyAnnotatedBy(model::Details d) throws ServerError

Restricts entities by who has annotated them with an model::Annotation matching the other filters. As onlyOwnedBy, the model::Details::getOwner and model::Details::getGroup information is combined with an AND condition.

Parameters

d
Can be null, in which case any previous restriction is removed.

void notAnnotatedBy(model::Details d) throws ServerError

Restricts entities by who has not annotated them with an model::Annotation matching the other filters. As notOwnedBy, the model::Details::getOwner and model::Details::getGroup information is combined with an AND condition.

Parameters

d
Can be null, in which case any previous restriction is removed.

void onlyAnnotatedWith(StringSet classes) throws ServerError

Restricts entities to having an model::Annotation of all the given types. This is useful in combination with the other onlyAnnotated* methods to say, e.g., only annotated with a file by user X. By default, this value is null and imposes no restriction. Passing an empty array implies an object that is not annotated at all. Note: If the semantics were OR, then a client would have to query each class individually, and compare all the various values, checking which ids are where. However, since this method defaults to AND, multiple calls (optionally with isMergedBatches and isReturnUnloaded) and combine the results. Duplicate ids are still possible so a set of some form should be used to collect the results.

Parameters

classes
Can be empty, in which case restriction is removed.

void addOrderByAsc(string path) throws ServerError

A path from the target entity which will be added to the current stack of order statements applied to the query.

Parameters

path
Non-null.

See Also

unordered

void addOrderByDesc(string path) throws ServerError

A path from the target entity which will be added to the current stack of order statements applied to the query.

Parameters

path
Non-null.

See Also

unordered

void unordered() throws ServerError

Removes the current stack of order statements.

See Also

addOrderByAsc
addOrderByDesc

void fetchAnnotations(StringSet classes) throws ServerError

Queries the database for all model::Annotation annotations of the given types for all returned instances.

Parameters

classes
Can be empty, which removes previous fetch setting.

void fetchAlso(StringSet fetches) throws ServerError

Adds a fetch clause for loading non-annotation fields of returned entities. Each fetch is a hibernate clause in dot notation.

Parameters

fetches
Can be empty, which removes previous fetch setting.

void resetDefaults() throws ServerError

Resets all settings (non-query state) to the original default values, as if the instance had just be created.

void byGroupForTags(string group) throws ServerError

Returns transient (without ID) model::TagAnnotation instances which represent all the model::TagAnnotation tags in the given group. The entities are transient and without ownership since multiple users can own the same tag. This method will override settings for types.

Parameters

group
Can be null or empty to return all tags.

void byTagForGroups(string tag) throws ServerError

Creates a query which will return transient (without ID) model::TagAnnotation instances which represent all the model::TagAnnotation tag groups which the given tag belongs to. The entities are transient and without ownership since multiple users can own the same tag group. This method will override settings for types.

Parameters

tag
Can be null or empty to return all groups.

void byFullText(string query) throws ServerError

Passes the query as is to the Lucene backend.

Parameters

query
May not be null or of zero length.

void byLuceneQueryBuilder(string fields, string from, string to, string dateType, string query) throws ServerError

Builds a Lucene query and passes it to the Lucene backend.

Parameters

fields
The fields (comma separated) to search in (name, description, ...)
from
The date range from, in the form YYYYMMDD (may be null)
to
The date range to (inclusive), in the form YYYYMMDD (may be null)
dateType
DATE_TYPE_ACQUISITION or DATE_TYPE_IMPORT
query
May not be null or of zero length.

void bySimilarTerms(StringSet terms) throws ServerError

Returns transient (without ID) model::TextAnnotation instances which represent terms which are similar to the given terms. For example, if the argument is cell, one return value might have as its textValue: cellular while another has cellularize. No filtering or fetching is performed.

Parameters

terms
Cannot be empty.

void byHqlQuery(string query, sys::Parameters params) throws ServerError

Delegates to IQuery::findAllByQuery method to take advantage of the and, or, and not methods, or queue-semantics.

Parameters

query
Not null.
p
May be null. Defaults are then in effect.

See Also

IQuery::findAllByQuery

void bySomeMustNone(StringSet some, StringSet must, StringSet none) throws ServerError

Builds a Lucene query and passes it to byFullText.

Parameters

some
Some (at least one) of these terms must be present in the document. May be null.
must
All of these terms must be present in the document. May be null.
none
None of these terms may be present in the document. May be null.

void byAnnotatedWith(AnnotationList examples) throws ServerError

Finds entities annotated with an model::Annotation similar to the example. This does not use Hibernate's IQuery::findByExample Query-By-Example} mechanism, since that cannot handle joins. The fields which are used are:

If the main content is null it is assumed to be a wildcard searched, and only the type of the annotation is searched. Currently, ListAnnotations are not supported.

Parameters

examples
Not empty.

void clearQueries() throws ServerError

Removes all active queries (leaving resetDefaults settings alone), such that activeQueries will return 0.

void and() throws ServerError

Applies the next by* method to the previous by* method, so that a call hasNext, next, or results sees only the intersection of the two calls. For example,

service.onlyType(Image.class);
service.byFullText("foo");
service.intersection();
service.byAnnotatedWith(TagAnnotation.class);
will return only the Images with TagAnnotations.

Calling this method overrides a previous setting of or or not. If there is no active queries (i.e. activeQueries > 0), then an ApiUsageException will be thrown.

void or() throws ServerError

Applies the next by* method to the previous by* method, so that a call hasNext, next or results sees only the union of the two calls. For example,

service.onlyType(Image.class);
service.byFullText("foo");
service.or();
service.onlyType(Dataset.class);
service.byFullText("foo");
will return both Images and Datasets together. Calling this method overrides a previous setting of and or not. If there is no active queries (i.e. activeQueries > 0), then an ApiUsageException will be thrown.

void not() throws ServerError

Applies the next by* method to the previous by* method, so that a call hasNext, next, or results sees only the intersection of the two calls. For example,

service.onlyType(Image.class);
service.byFullText("foo");
service.complement();
service.byAnnotatedWith(TagAnnotation.class);
will return all the Images not annotated with TagAnnotation.

Calling this method overrides a previous setting of or or and. If there is no active queries (i.e. activeQueries > 0), then an ApiUsageException will be thrown.

bool hasNext() throws ServerError

Returns true if another call to next is valid. A call to next may throw an exception for another reason, however.

model::IObject next() throws ServerError

Returns the next entity from the current query. If the previous call returned the last entity from a given query, the first entity from the next query will be returned and activeQueries decremented. Since this method only returns the entity itself, a single call to currentMetadata may follow this call to gather the extra metadata which is returned in the map via results.

Exceptions

ApiUsageException
if hasNext returns false.

IObjectList results() throws ServerError

Returns up to getBatchSize batch size number of results along with the related query metadata. If isMergedBatches batches are merged then the results from multiple queries may be returned together.

Exceptions

ApiUsageException
if hasNext returns false.

SearchMetadata currentMetadata() throws ServerError

Provides access to the extra query information (for example Lucene score and boost values) for a single call to next. This method may only be called once for any given call to next.

SearchMetadataList currentMetadataList() throws ServerError

Provides access to the extra query information (for example Lucene score and boost values) for a single call to results. This method may only be called once for any given call to results.

void remove() throws ServerError

Unsupported operation.


Home Previous Up Next Index