Search for one or more terms in the values of an app

Last updated: 6/9/2026

Search for one or more terms in the values of an app by using the SearchResults method.

Examples

Example 1:

No field in the app is locked and there are no current selections.

The first step of the example is to create a chart with two dimensions City and Country (set in qFieldDefs ) and one measure Count(Rainfall) (set in qDef).

1. Create the chart object BC01.

The client sends:

{ "jsonrpc": "2.0", "id": 2, "method": "CreateSessionObject", "handle": 1, "params": [ { "qInfo": { "qId": "BC01", "qType": "Chart" }, "qHyperCubeDef": { "qStateName": "$", "qDimensions": [ { "qLibraryId": "", "qNullSuppression": false, "qIncludeElemValue": false, "qDef": { "qGrouping": "N", "qFieldDefs": [ "City" ], "qFieldLabels": [ "ProductName label" ], "qSortCriterias": [ { "qSortByState": 0, "qSortByFrequency": 0, "qSortByNumeric": 0, "qSortByAscii": 0, "qSortByLoadOrder": 1, "qSortByExpression": 0, "qExpression": { "qv": "" } }, { "qSortByState": 0, "qSortByFrequency": 0, "qSortByNumeric": 0, "qSortByAscii": 0, "qSortByLoadOrder": 1, "qSortByExpression": 0, "qExpression": { "qv": "" } } ], "qNumberPresentations": [ { "qType": "U", "qnDec": 10, "qUseThou": 0, "qFmt": "", "qDec": ".", "qThou": " " } ], "qReverseSort": false }, "qOtherTotalSpec": { "qOtherMode": "OTHER_OFF", "qOtherCounted": { "qv": "10" }, "qOtherLimit": { "qv": "0.05" }, "qOtherLimitMode": "OTHER_GT_LIMIT", "qSuppressOther": false, "qForceBadValueKeeping": true, "qApplyEvenWhenPossiblyWrongResult": true, "qGlobalOtherGrouping": false, "qOtherCollapseInnerDimensions": false, "qOtherSortMode": "OTHER_SORT_DESCENDING", "qTotalMode": "TOTAL_OFF", "qReferencedExpression": { "qv": "" } } }, { "qLibraryId": "", "qNullSuppression": false, "qIncludeElemValue": false, "qDef": { "qGrouping": "N", "qFieldDefs": [ "Country" ], "qFieldLabels": [ "ProductName label" ], "qSortCriterias": [ { "qSortByState": 0, "qSortByFrequency": 0, "qSortByNumeric": 0, "qSortByAscii": 0, "qSortByLoadOrder": 1, "qSortByExpression": 0, "qExpression": { "qv": "" } }, { "qSortByState": 0, "qSortByFrequency": 0, "qSortByNumeric": 0, "qSortByAscii": 0, "qSortByLoadOrder": 1, "qSortByExpression": 0, "qExpression": { "qv": "" } } ], "qNumberPresentations": [ { "qType": "U", "qnDec": 10, "qUseThou": 0, "qFmt": "", "qDec": ".", "qThou": " " } ], "qReverseSort": false }, "qOtherTotalSpec": { "qOtherMode": "OTHER_OFF", "qOtherCounted": { "qv": "10" }, "qOtherLimit": { "qv": "0.05" }, "qOtherLimitMode": "OTHER_GT_LIMIT", "qSuppressOther": false, "qForceBadValueKeeping": true, "qApplyEvenWhenPossiblyWrongResult": true, "qGlobalOtherGrouping": false, "qOtherCollapseInnerDimensions": false, "qOtherSortMode": "OTHER_SORT_DESCENDING", "qTotalMode": "TOTAL_OFF", "qReferencedExpression": { "qv": "" } } } ], "qMeasures": [ { "qLibraryId": "", "qSortBy": { "qSortByState": 0, "qSortByFrequency": 0, "qSortByNumeric": 0, "qSortByAscii": 0, "qSortByLoadOrder": 1, "qSortByExpression": 0, "qExpression": { "qv": "" } }, "qDef": { "qLabel": "Chart HC Properties measures label", "qDescription": "Chart HC Properties measure description", "qTags": [ "tags" ], "qGrouping": "N", "qDef": "Count(Rainfall)", "qNumFormat": { "qType": "U", "qnDec": 10, "qUseThou": 0, "qFmt": "", "qDec": ".", "qThou": " " }, "qRelative": false, "qBrutalSum": false, "qAggrFunc": "", "qAccumulate": 0, "qReverseSort": false } }, { "qLibraryId": "", "qSortBy": { "qSortByState": 0, "qSortByFrequency": 0, "qSortByNumeric": 0, "qSortByAscii": 0, "qSortByLoadOrder": 1, "qSortByExpression": 0, "qExpression": { "qv": "" } } } ], "qSuppressZero": false, "qSuppressMissing": false, "qInterColumnSortOrder": [], "qInitialDataFetch": [ { "qTop": 0, "qLeft": 0, "qHeight": 2, "qWidth": 3 } ] } } ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 2, "result": { "qReturn": { "qType": "GenericObject", "qHandle": 2, "qGenericType": "Chart", "qGenericId": "BC01" } }, "change": [ 2 ] }

The chart object is created and the handle is 2.

2. Search for the values associated to fra in the app (qTerm is fra).

All the values in the app are in optional state. The search context (qContext) is LockedFieldsOnly (default value). Since there are no locked fields, the search is performed on all values. It is equivalent to the search context Cleared.

The number of search results that contain search hits is limited to 2 (value of the parameter qCount).

The client sends:

{ "jsonrpc": "2.0", "id": 3, "method": "SearchResults", "handle": 1, "params": [ {}, [ "fra" ], { "qOffset": 0, "qCount": 2 } ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 3, "result": { "qResult": { "qSearchTerms": [ "fra" ], "qTotalNumberOfGroups": 8, "qSearchGroupArray": [ { "qId": 0, "qGroupType": "DatasetType", "qSearchTermsMatched": [ 0 ], "qTotalNumberOfItems": 1, "qItems": [ { "qItemType": "Field", "qTotalNumberOfMatches": 1, "qIdentifier": "Country", "qItemMatches": [ { "qText": "France", "qRanges": [ { "qCharPos": 0, "qCharCount": 3, "qTerm": 0 } ] } ] } ] }, { "qId": 1, "qGroupType": "DatasetType", "qSearchTermsMatched": [ 0 ], "qTotalNumberOfItems": 1, "qItems": [ { "qItemType": "Field", "qTotalNumberOfMatches": 2, "qIdentifier": "Swedish", "qItemMatches": [ { "qText": "Framåt", "qRanges": [ { "qCharPos": 0, "qCharCount": 3, "qTerm": 0 } ] }, { "qText": "Golf är en utav de sporter som inte kräver en standardiserad plats att spela på. Golfbanorna varierar mycket från region till region, Från den råa, naturliga skönheten hos brittiska banor till de minutiöst hållna banorna i USA.", "qRanges": [ { "qCharPos": 109, "qCharCount": 3, "qTerm": 0 }, { "qCharPos": 135, "qCharCount": 3, "qTerm": 0 } ] } ] } ] } ] } } }

The list of search terms is returned.

In this example, there is only one term that is searched (in qSearchTerms). Consequently, the list of indexes corresponding to the search terms in each group (qSearchTermsMatched ) is always set to 0.

The total number of groups containing search results is 8 (qTotalNumberOfGroups). Because the number of groups was limited to 2 in the input request (qCount is 2), the SearchResults method returns the search matches for the 2 first search groups (groups with identifiers 0 and 1).

Both search groups have DatasetType as type, meaning that the search is performed in the data of the app.

The number of items in each group is 1 (qTotalNumberOfItems is 1).

In the first search group, there is one search match in the field Country. The match is the country France.

In the second search group, there are two search matches in the field Swedish.

For each search match, the position of the match is given in qRanges.

SearchResults method.

Example 2:

No field in the app is locked.

The first step of the example is to create a chart with two dimensions City and Country (set in qFieldDefs ) and one measure Count(Rainfall) (set in qDef).

1. Create the chart object BC01.

The client sends:

}

The engine returns:

{ "jsonrpc": "2.0", "id": 2, "result": { "qReturn": { "qType": "GenericObject", "qHandle": 2, "qGenericType": "Chart", "qGenericId": "BC01" } }, "change": [ 2 ] }

The chart object is created and the handle is 2.

2. Get the handle of the field City .

The client sends:

{ "jsonrpc": "2.0", "id": 3, "method": "GetField", "handle": 1, "params": [ "City" ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 3, "result": { "qReturn": { "qType": "Field", "qHandle": 3 } } }

The handle of the field City is 3.

3. Select the values Anglet, Apremont and Vittel in the field City .

The client sends:

{ "jsonrpc": "2.0", "id": 4, "method": "SelectValues", "handle": 3, "params": [ [ { "qText": "Anglet" }, { "qText": "Apremont" }, { "qText": "Vittel" } ], false, false ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 4, "result": { "qReturn": true }, "change": [ 1, 3 ] }

The values Anglet, Apremont and Vittel are selected.

SelectValues method.

4. Get the layout of the chart object. The handle of the request is 2 because the handle of the list object is 2.

The client sends:

{ "jsonrpc": "2.0", "id": 5, "method": "GetLayout", "handle": 2, "params": [] }

The engine returns:

{ "jsonrpc": "2.0", "id": 5, "result": { "qLayout": { "qInfo": { "qId": "BC01", "qType": "Chart" }, "qSelectionInfo": {}, "qHyperCube": { "qStateName": "$", "qSize": { "qcx": 4, "qcy": 3 }, "qDimensionInfo": [ { "qFallbackTitle": "ProductName label", "qApprMaxGlyphCount": 30, "qCardinal": 7532, "qSortIndicator": "A", "qGroupFallbackTitles": [ "ProductName label" ], "qGroupPos": 0, "qStateCounts": { "qLocked": 0, "qSelected": 3, "qOption": 0, "qDeselected": 0, "qAlternative": 7529, "qExcluded": 0, "qSelectedExcluded": 0, "qLockedExcluded": 0 }, "qTags": [ "$text" ], "qDimensionType": "D", "qGrouping": "N", "qNumFormat": { "qType": "R", "qnDec": 14, "qUseThou": 1, "qFmt": "##############", "qDec": ".", "qThou": "," }, "qIsAutoFormat": true, "qGroupFieldDefs": [ "City" ] }, { "qFallbackTitle": "ProductName label", "qApprMaxGlyphCount": 14, "qCardinal": 22, "qSortIndicator": "A", "qGroupFallbackTitles": [ "ProductName label" ], "qGroupPos": 0, "qStateCounts": { "qLocked": 0, "qSelected": 0, "qOption": 1, "qDeselected": 0, "qAlternative": 0, "qExcluded": 21, "qSelectedExcluded": 0, "qLockedExcluded": 0 }, "qTags": [ "$ascii", "$text" ], "qDimensionType": "D", "qGrouping": "N", "qNumFormat": { "qType": "R", "qnDec": 14, "qUseThou": 1, "qFmt": "##############", "qDec": ".", "qThou": "," }, "qIsAutoFormat": true, "qGroupFieldDefs": [ "Country" ] } ], "qMeasureInfo": [ { "qFallbackTitle": "Chart HC Properties measures label", "qApprMaxGlyphCount": 1, "qCardinal": 0, "qSortIndicator": "A", "qNumFormat": { "qType": "I", "qnDec": 0, "qUseThou": 1, "qFmt": "###0", "qDec": "." }, "qMin": 1, "qMax": 1, "qIsAutoFormat": true, "qAttrExprInfo": [] }, { "qApprMaxGlyphCount": 1, "qCardinal": 0, "qSortIndicator": "A", "qNumFormat": { "qType": "U", "qnDec": 0, "qUseThou": 0 }, "qMin": "NaN", "qMax": "NaN", "qIsAutoFormat": true, "qAttrExprInfo": [] } ], "qEffectiveInterColumnSortOrder": [ 0, 1, 2, 3 ], "qGrandTotalRow": [ { "qText": "1", "qNum": 1, "qElemNumber": -1, "qState": "X", "qIsTotalCell": true }, { "qText": "-", "qNum": "NaN", "qElemNumber": -1, "qState": "X", "qIsTotalCell": true } ], "qDataPages": [ { "qMatrix": [ [ { "qText": "Vittel", "qNum": "NaN", "qElemNumber": 6184, "qState": "S" }, { "qText": "France", "qNum": "NaN", "qElemNumber": 6, "qState": "O" }, { "qText": "1", "qNum": 1, "qElemNumber": 0, "qState": "L" } ], [ { "qText": "Apremont", "qNum": "NaN", "qElemNumber": 6387, "qState": "S" }, { "qText": "France", "qNum": "NaN", "qElemNumber": 6, "qState": "O" }, { "qText": "1", "qNum": 1, "qElemNumber": 0, "qState": "L" } ], [ { "qText": "Anglet", "qNum": "NaN", "qElemNumber": 7033, "qState": "S" }, { "qText": "France", "qNum": "NaN", "qElemNumber": 6, "qState": "O" }, { "qText": "1", "qNum": 1, "qElemNumber": 0, "qState": "L" } ] ], "qTails": [ { "qUp": 0, "qDown": 0 }, { "qUp": 0, "qDown": 0 } ], "qArea": { "qLeft": 0, "qTop": 0, "qWidth": 3, "qHeight": 3 } } ], "qPivotDataPages": [], "qStackedDataPages": [], "qMode": "S", "qNoOfLeftDims": -1 } } } }

The values Anglet, Apremont and Vittel are selected.

5. Search for the values associated to fra. The search context is CurrentSelections. The search is performed on the values associated to the selected values.

The number of search results that contain search hits is limited to 2 (value of the parameter qCount).

The client sends:

{ "jsonrpc": "2.0", "id": 6, "method": "SearchResults", "handle": 1, "params": [ { "qContext": "CurrentSelections" }, [ "fra" ], { "qOffset": 0, "qCount": 2 } ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 6, "result": { "qResult": { "qSearchTerms": [ "fra" ], "qTotalNumberOfGroups": 5, "qSearchGroupArray": [ { "qId": 0, "qGroupType": "DatasetType", "qSearchTermsMatched": [ 0 ], "qTotalNumberOfItems": 1, "qItems": [ { "qItemType": "Field", "qTotalNumberOfMatches": 1, "qIdentifier": "Country", "qItemMatches": [ { "qText": "France", "qRanges": [ { "qCharPos": 0, "qCharCount": 3, "qTerm": 0 } ] } ] } ] }, { "qId": 1, "qGroupType": "DatasetType", "qSearchTermsMatched": [ 0 ], "qTotalNumberOfItems": 1, "qItems": [ { "qItemType": "Field", "qTotalNumberOfMatches": 2, "qIdentifier": "Swedish", "qItemMatches": [ { "qText": "Framåt", "qRanges": [ { "qCharPos": 0, "qCharCount": 3, "qTerm": 0 } ] }, { "qText": "Golf är en utav de sporter som inte kräver en standardiserad plats att spela på. Golfbanorna varierar mycket från region till region, Från den råa, naturliga skönheten hos brittiska banor till de minutiöst hållna banorna i USA.", "qRanges": [ { "qCharPos": 109, "qCharCount": 3, "qTerm": 0 }, { "qCharPos": 135, "qCharCount": 3, "qTerm": 0 } ] } ] } ] } ] } } }

The list of search terms is returned.

The total number of groups containing search results is 5 (qTotalNumberOfGroups). Because the number of groups was limited to 2 in the input request (qCount is 2), the SearchResults method returns the search matches for the 2 first search groups (groups with identifiers 0 and 1).

Both search groups have DatasetType as type, meaning that the search is performed in the data of the app.

The number of items in each group is 1 (qTotalNumberOfItems is 1).

In the first search group, there is one search match in the field Country. The match is the country France.

In the second search group, there are two search matches in the field Swedish.

For each search match, the position of the match is given in qRanges.

SearchResults method.

6. Select the values associated to fra.

There are some current selections in the app and the search context is CurrentSelections, meaning that the new selections are applied in addition to the previous selections.

The client sends:

{ "jsonrpc": "2.0", "id": 7, "method": "SelectAssociations", "handle": 1, "params": [ { "qContext": "CurrentSelections" }, [ "fra" ], 0 ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 7, "result": {}, "change": [ 1, 2, 3 ] }

The country France is selected.

SelectAssociations method.

7. Get the layout of the chart object. The handle of the request is 2 because the handle of the chart object is 2.

The client sends:

{ "jsonrpc": "2.0", "id": 8, "method": "GetLayout", "handle": 2, "params": [] }

The engine returns:

{ "jsonrpc": "2.0", "id": 8, "result": { "qLayout": { "qInfo": { "qId": "BC01", "qType": "Chart" }, "qSelectionInfo": {}, "qHyperCube": { "qStateName": "$", "qSize": { "qcx": 4, "qcy": 3 }, "qDimensionInfo": [ { "qFallbackTitle": "ProductName label", "qApprMaxGlyphCount": 30, "qCardinal": 7532, "qSortIndicator": "A", "qGroupFallbackTitles": [ "ProductName label" ], "qGroupPos": 0, "qStateCounts": { "qLocked": 0, "qSelected": 3, "qOption": 0, "qDeselected": 0, "qAlternative": 118, "qExcluded": 7411, "qSelectedExcluded": 0, "qLockedExcluded": 0 }, "qTags": [ "$text" ], "qDimensionType": "D", "qGrouping": "N", "qNumFormat": { "qType": "R", "qnDec": 14, "qUseThou": 1, "qFmt": "##############", "qDec": ".", "qThou": "," }, "qIsAutoFormat": true, "qGroupFieldDefs": [ "City" ] }, { "qFallbackTitle": "ProductName label", "qApprMaxGlyphCount": 14, "qCardinal": 22, "qSortIndicator": "A", "qGroupFallbackTitles": [ "ProductName label" ], "qGroupPos": 0, "qStateCounts": { "qLocked": 0, "qSelected": 1, "qOption": 0, "qDeselected": 0, "qAlternative": 0, "qExcluded": 21, "qSelectedExcluded": 0, "qLockedExcluded": 0 }, "qTags": [ "$ascii", "$text" ], "qDimensionType": "D", "qGrouping": "N", "qNumFormat": { "qType": "R", "qnDec": 14, "qUseThou": 1, "qFmt": "##############", "qDec": ".", "qThou": "," }, "qIsAutoFormat": true, "qGroupFieldDefs": [ "Country" ] } ], "qMeasureInfo": [ { "qFallbackTitle": "Chart HC Properties measures label", "qApprMaxGlyphCount": 1, "qCardinal": 0, "qSortIndicator": "A", "qNumFormat": { "qType": "I", "qnDec": 0, "qUseThou": 1, "qFmt": "###0", "qDec": "." }, "qMin": 1, "qMax": 1, "qIsAutoFormat": true, "qAttrExprInfo": [] }, { "qApprMaxGlyphCount": 1, "qCardinal": 0, "qSortIndicator": "A", "qNumFormat": { "qType": "U", "qnDec": 0, "qUseThou": 0 }, "qMin": "NaN", "qMax": "NaN", "qIsAutoFormat": true, "qAttrExprInfo": [] } ], "qEffectiveInterColumnSortOrder": [ 0, 1, 2, 3 ], "qGrandTotalRow": [ { "qText": "1", "qNum": 1, "qElemNumber": -1, "qState": "X", "qIsTotalCell": true }, { "qText": "-", "qNum": "NaN", "qElemNumber": -1, "qState": "X", "qIsTotalCell": true } ], "qDataPages": [ { "qMatrix": [ [ { "qText": "Vittel", "qNum": "NaN", "qElemNumber": 6184, "qState": "S" }, { "qText": "France", "qNum": "NaN", "qElemNumber": 6, "qState": "S" }, { "qText": "1", "qNum": 1, "qElemNumber": 0, "qState": "L" } ], [ { "qText": "Apremont", "qNum": "NaN", "qElemNumber": 6387, "qState": "S" }, { "qText": "France", "qNum": "NaN", "qElemNumber": 6, "qState": "S" }, { "qText": "1", "qNum": 1, "qElemNumber": 0, "qState": "L" } ], [ { "qText": "Anglet", "qNum": "NaN", "qElemNumber": 7033, "qState": "S" }, { "qText": "France", "qNum": "NaN", "qElemNumber": 6, "qState": "S" }, { "qText": "1", "qNum": 1, "qElemNumber": 0, "qState": "L" } ] ], "qTails": [ { "qUp": 0, "qDown": 0 }, { "qUp": 0, "qDown": 0 } ], "qArea": { "qLeft": 0, "qTop": 0, "qWidth": 3, "qHeight": 3 } } ], "qPivotDataPages": [], "qStackedDataPages": [], "qMode": "S", "qNoOfLeftDims": -1 } } } }

The country France and the cities Anglet, Apremont and Vittel are selected.

Example 3:

The search context is LockedFieldsOnly, which means that the search is restricted to the values associated to the locked values.

The first step in this example is to lock some values. In particular: the cities Aachen and Aalborg from the field City.

In order to be able to lock some values in the field City, the handle of the field City must be retrieved.

1. Get the handle of the field City.

The client sends:

{ "jsonrpc": "2.0", "id": 2, "method": "GetField", "handle": 1, "params": [ "City" ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 2, "result": { "qReturn": { "qType": "Field", "qHandle": 2 } } }

The handle of the field City is 2.

2. Select the cities Aachen and Aalborg.

The handle of the request is 2 because the cities belong to the field City and the field City has 2 as a handle.

The client sends:

{ "jsonrpc": "2.0", "id": 3, "method": "SelectValues", "handle": 2, "params": [ [ { "qText": "Aachen" }, { "qText": "Aalborg" } ], false, false ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 3, "result": { "qReturn": true }, "change": [ 1, 2 ] }

The cities Aachen and Aalborg are selected.

Aachen is located in Germany and Aalborg is located in Denmark.

3. Lock the selected values in the field City.

The client sends:

{ "jsonrpc": "2.0", "id": 4, "method": "Lock", "handle": 2, "params": [] }

The engine returns:

{ "jsonrpc": "2.0", "id": 4, "result": { "qReturn": true } }

The values Aachen and Aalborg are locked.

4. Search for the values associated to the countries Canada and Denmark in the field Country.

The number of search results that contain search hits is limited to 2 (value of the parameter qCount).

The client sends:

{ "jsonrpc": "2.0", "id": 5, "method": "SearchResults", "handle": 1, "params": [ { "qSearchFields": [ "Country" ] }, [ "Canada", "Denmark" ], { "qOffset": 0, "qCount": 2 } ] }

The engine returns:

{ "jsonrpc": "2.0", "id": 5, "result": { "qResult": { "qSearchTerms": [ "Canada", "Denmark" ], "qTotalNumberOfGroups": 1, "qSearchGroupArray": [ { "qId": 0, "qGroupType": "DatasetType", "qSearchTermsMatched": [ 1 ], "qTotalNumberOfItems": 1, "qItems": [ { "qItemType": "Field", "qTotalNumberOfMatches": 1, "qIdentifier": "Country", "qItemMatches": [ { "qText": "Denmark", "qRanges": [ { "qCharPos": 0, "qCharCount": 7, "qTerm": 1 } ] } ] } ] } ] } } }

There is only one match: the country Denmark.

This result is explained by the fact that Aachen and Aalborg are locked values.

The SearchResults method returns search matches that are associated to the locked values.

The search terms are Canada and Denmark . In the field Country, only Denmark is associated to one of the locked value, since Aachen is located in Germany and Aalborg is located in Denmark.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – please let us know!

Leave your feedback here