Search Parameters
This section describes many of the most important parameters for the Query
action that you can use to restrict the document result set.
For more information about each of these parameters, refer to the IDOL Content component Help.
Text
The Text
parameter defines restrictions on the content of matching documents. You can specify restrictions in plain text, or by using Boolean and proximity operators.
If Text
contains plain text, for example airplane leases, the IDOL Content component treats the query as a conceptual query. It tokenizes the query text, removes stop words, and stems the remaining tokens to produce a collection of terms.
NOTE: These functions are language-specific. For more information about language configuration in IDOL, refer to the IDOL Content component Help, and IDOL Expert.
The IDOL Content component finds documents that contains these terms, and uses statistical algorithms to quantify the relevance of the match to the original query. It assigns a relevancy score to each result document. By default, Content also uses this relevancy score to sort the results of the query.
For example:
action=query&text=the airplane leases
The IDOL Content component tokenizes this query text into the, airplane, and leases. The term the is a stop word, so Content ignores it. It stems the other two terms to produce the terms airplan and leas. Stemming allows Content to match documents that contain alternate forms of the words airplane and leases (for example, lease, leasing, and leased also stem to leas).
If Text
contains Boolean or proximity operators, such as AND
, or OR
, Content treats the query as a Boolean query. As with conceptual queries, Content stems the search terms and ignores stop words, but documents match the query only if they satisfy the Boolean or proximity expression.
FieldText
The FieldText
parameter defines restrictions on the fields of documents that match the query. FieldText
restrictions have the following format:
FIELDOPERATOR{Value1[,Value2,...]}:FieldName1[:FieldName2:...]
where,
FIELDOPERATOR
|
is the type of comparison or test to perform on the value of the specified fields, against the specified values. |
Value1[,Value2,...]
|
is a comma-separated list of field values. |
FieldName1[:FieldName2:...]
|
is a colon-separated list of field names. |
There are more than 40 different field operators. The following examples demonstrate the FieldText
restriction format and some of the most common field operators. For a full list of field operators, refer to the IDOL Content component Help. For more information about fields and optimizations for the FieldText
queries, see Configure Fields.
NOTE: By default, FieldText
matches are not case sensitive. For more information about case sensitive search, refer to IDOL Expert.
The following FieldText
restriction matches documents whose DOCUMENT_TYPE
field contains the value record:
FieldText=MATCH{record}:DOCUMENT_TYPE
The following FieldText
restriction matches documents whose FILETYPE
field contains one of the values pdf, doc, or txt:
FieldText=MATCH{pdf,doc,txt}:FILETYPE
The following FieldText
restriction matches documents whose DIR
or DIRECTORY
field exactly matches one of docs, archive, or work:
FieldText=MATCH{docs,archive,work}:DIR:DIRECTORY
You can combine FieldText
restrictions by using Boolean operators, such as AND
, OR
, and NOT
, and group the restrictions by using parentheses. For example:
FieldText=MATCH{dog}:ANIMAL+AND+(MATCH{celery}:VEGETABLE+OR+NOT+MATCH{quartz}:MINERAL)
The IDOL Content component also includes field operators for numerical comparison. The following FieldText
restriction matches documents for which SCORE1
is greater than .95
and SCORE2
is less than .85
:
FieldText=GREATER{.95}:SCORE1+AND+LESS{.85}:SCORE2
The following FieldText
restriction matches documents that have a COUNT
field, regardless of its value:
FieldText=EXISTS{}:COUNT
The following FieldText
restriction matches documents whose BRAND
field contains tech as a substring:
FieldText=STRING{tech}:BRAND
The following FieldText
restriction matches documents whose EMOTION
field contains a string that has the same stem as the word loving.
FieldText=TERM{loving}:EMOTION
For example, if the EMOTION
field has any of the values love, loving, loves, or lover, the document matches.
The following FieldText
restriction matches documents whose position (stored in the LAT
and LONG
fields) is within a distance of 5 kilometers from the point with latitude 52.2°N and longitude 0.12° E.
FieldText=DISTSPHERICAL{52.2,0.12,5}:LAT:LONG
The following FieldText
restriction matches documents whose DUE_DATE
is before the current time.
FieldText=LTNOW{}:DUE_DATE
Combine
The Combine
parameter contains instructions on how to treat certain groups of documents as a single result for the Query
action.
The most important value for Combine
is Simple
. By default, when you index long documents, the IDOL Content component splits the documents into shorter sections. When Content processes a query, it can return each of these sections as a separate search result. If you set Combine
to Simple
, Content returns only the best matching section from each document.
It is a best practice to set Combine
to Simple
in every Content Query
unless there is a specific reason not to.
DatabaseMatch
Every document in the IDOL Content component belongs to exactly one database. The DatabaseMatch
parameter specifies a comma-separated list of databases that resulting documents can come from.
By default (if DatabaseMatch
is missing or empty), Content retrieves results from any database. Content applies database restrictions early in the query process, and these restrictions are generally quick, so using a DatabaseMatch
can improve the performance of your query.
It is a best practice to set DatabaseMatch
in every Content Query
to be as restrictive as possible.
NOTE: A DatabaseMatch restriction is equivalent to the following FieldText
operation:
MATCH{DatabaseNames}:autn_database
Start and MaxResults
Together, Start
and MaxResults
control the paging of query results.
MaxResults
indicates the total maximum number of results to retrieve from the index. By default, the IDOL Content component returns the results in order of the relevance score, which indicates how well the document matches the query. You can change the order of the results by setting the Sort
parameter (see Sort). Content returns the top results according to your sort, up to the value of MaxResults
.
Start
indicates the first result to return from the set. This option allows you to return results in pages. For example, the following query returns up to 50 results. If there are more than 50 results, it returns the best 50.
action=Query&Text=bananas&MaxResults=50
For the following query, Content finds the best 50 results that match the query, and then returns these results from the eleventh best onwards. The response therefore contains 40 results (results 11 to 50).
action=Query&Text=bananas&MaxResults=50&Start=11
MinScore
The Minscore
parameter specifies the smallest relevancy score that a document must have to the query for the IDOL Content component to return it as a result. For example:
action=Query&Text=aircraft&MinScore=60
If this query has 10 matching documents, with scores of 100, 90, 80, 70, and so on down to 10, the query returns five results (the documents with relevancy scores of 100, 90, 80, 70, and 60).
StoreState, StateMatchID, and StateDontMatchID
The StoreState
parameter allows you to save an IDOL Content component search. When you set StoreState
to True
, Content returns an alphanumeric token with the query. This token is a reference to the original set of search results.
You can set this token as the value of the StateMatchID
parameter to restrict the results of a query to only those in the original stored search. In this way, you can use StoreState
and StateMatchID
together to implement 'search within a search' functionality in IDOL.
The StateDontMatchID
parameter is the opposite of StateMatchID
. When you set StateDontMatchID
to the value of a stored state token , the query excludes any result that was a result in the original search. Effectively, StoreState
and StateDontMatchID
implement 'search outside a search' functionality.
UserMetaFields
The UserMetaFields
parameter allows you to combine the field values in result documents into a new field (a metafield) dynamically at query time. This method allows you to create on-the-fly analytics for your documents. The format of UserMetaFields
is:
UserMetaFields=OPERATION{UserFieldName}:DocumentFieldName
The following examples demonstrate both the UserMetaFields
format, and some of the existing operators. For a full list of operators, refer to the IDOL Content component Help.
In the following example, the TOTAL
metafield for a matching document is the sum of all the PRICE
fields in that document:
UserMetaFields=ADD{TOTAL}:PRICE
You can create multiple metafields with one UserMetaFields parameter. In the following example, the TOTALCOST
metafield for a matching document contains the sum of all its COST
fields, and the AVGREVENUE
field contains the average (mean) of the REVENUE
fields:
UserMetaFields=ADD{TOTALCOST}:COST+MEAN{AVGREVENUE}:REVENUE
You can use metafields in the Sort
and FieldText
parameters of the Query
where you create them. In the following example, the IDOL Content component creates a MAXPRICE
metafield for each document that matches the initial query stages, which is the maximum of the PRICE
fields in the document. The query returns only documents for which the MAXPRICE
metafield is greater than 500
.
UserMetaFields=MAX{MAXPRICE}:PRICE&FieldText=GREATER{500}:autn_user_MAXPRICE