.. _search_syntax:
.. rst-class:: chapter-with-expand
Search Syntax
-------------
The query input box can be used to construct a search query. This section
describes the syntax of a search query.
Search queries can contain:
* Model type and model name references
* Model attribute and nested model attribute references
* Key words
* Brackets for grouping
* Query string to search for
Valid query string characters are:
* alphanumeric characters
* !@#$%^&*-_=+<,.>/?\|[{]}~`
* to search for single quote in a string, wrap the string in double quotes
* to search for double quote in a string, wrap the string in single quotes
Since a search query is carried out on models, the specific model type and
model name can be specified in the query.
The query format is indicated below:
``type/name`` is the syntax for a full reference to a model type (for
example relation, data, or device) and model name (for example Countries).
A number of keywords are available to construct a search query.
Keyword Types
.............
Three types of keywords are available:
* Specification - WITH
* Matching - IS, LIKE
* Grouping - AND, OR
.. tabularcolumns:: |p{2.5cm}|p{13cm}|
+----------+-------------------------------------------------------------+
| Keyword | Description and Examples |
+==========+=============================================================+
| WITH | Restricts the search to look for only specific data types. |
| | In the example below we have specified the data type |
| | Countries and so only countries will be returned. |
| | |
| | :: |
| | |
| | ((data/Countries WITH country_name LIKE Kingdom) AND |
| | (data/Countries WITH country_name LIKE Unite )) |
| | |
+----------+-------------------------------------------------------------+
| IS | For a result to be returned the data attribute must match |
| | exactly the 'input'. In the example below the 'input' |
| | is Spain and only a Country with the attribute |
| | country_name Spain will be returned. If 'North Spain and |
| | South Spain existed they would not be returned. In the |
| | example below we have specified the data type Countries |
| | and so only countries will be returned. If we had not |
| | specified a data type then the search would cover all |
| | data types looking for an attribute country_name. |
| | |
| | :: |
| | |
| | country_name IS Spain |
| | |
| | data/Countries WITH country_name IS Spain |
| | |
| | Another example with a model tag as reference: |
| | |
| | :: |
| | |
| | tag IS "Feature A member" |
| | |
+----------+-------------------------------------------------------------+
| CONTAINS | Matching is done by substring and is the default parameter. |
| | For a result to be returned, the data attribute must |
| | contain 'input'. In the example below, the 'input' |
| | is 'Sw' and the search would find both 'Sweden' and |
| | 'Switzerland'. |
| | |
| | :: |
| | |
| | data/Countries WITH country_name CONTAINS Sw |
| | |
+----------+-------------------------------------------------------------+
.. tabularcolumns:: |p{2.5cm}|p{13cm}|
+----------+-------------------------------------------------------------+
| Keyword | Description and Examples |
+==========+=============================================================+
| LIKE | Matching is done by fuzzy search. |
| | For a result to be returned, the data attribute must |
| | nearly match 'input'. In the example below, the 'input' |
| | is 'swe' and the search would find both 'Sweden' and |
| | 'Switzerland'. |
| | |
| | :: |
| | |
| | data/Countries WITH country_name LIKE swe |
| | |
+----------+-------------------------------------------------------------+
| AND | This grouping term allows you to combine different |
| | searches and only finds a result where both conditions |
| | are met. The example below the search would find 'United |
| | Kingdom' but not the 'Kingdom of Bhutan' as in this case |
| | the second condition (LIKE Unite) is not true. |
| | |
| | :: |
| | |
| | ((data/Countries WITH country_name LIKE Kingdom) AND |
| | (data/Countries WITH country_name LIKE Unite )) |
| | |
+----------+-------------------------------------------------------------+
| OR | This grouping term allows you to combine different |
| | searches and matches a result where any one or both of |
| | the conditions are met. The example search below would |
| | find 'United Kingdom', 'United States' and 'Kingdom of |
| | Bhutan'. |
| | |
| | :: |
| | |
| | ((data/Countries WITH country_name LIKE Kingdom) OR |
| | (data/Countries WITH country_name LIKE Unite)) |
| | |
+----------+-------------------------------------------------------------+
Search Syntax Diagrams
......................
|search-syntax|
Search Examples
...............
Where the attribute of a model is nested in an object, the reference
to the attribute in the search query requires a model type
specification.
For example, for a model ``data/User`` with an attribute in a nested object
called ``account_information``, the query should take the model type
(``data``) specifier:
::
data/User WITH data.account_information.credential_policy IS Default
The following query *will not* yield results:
::
data/User WITH account_information.credential_policy IS Default
Brackets should be used in a query with matching and grouping operators.
In a query containing no model references, brackets are evaluated first.
The order of bracket evaluation is inner to outer brackets.
Example Queries (line breaks added):
::
(((data/Countries WITH pstn_access_prefix IS 9) AND
(data/Countries WITH emergency__access_prefix IS 112))
OR (data/Countries WITH international_access_prefix IS 00))
Search String Format
....................
The string to search for can be specified with the following properties:
Multi-word and quotes
Enclose in quotes. Single- and double quotes are supported. Example: ``'United States'``
When single word or multi-word values contain a single or double quote, the
string needs to be enclosed in double or single quotes respectively,
for example: ``"L'Amour"``.
Case sensitivity
Use the appropriate operator (LIKE)
In a query containing model references, brackets and grouping keywords, the
query is evaluated in the order.
.. tabularcolumns:: |p{1.5cm}|p{2cm}|p{10.5cm}|
+-------+----------+---------------------------------------------+
| Order | Element | Description |
+=======+==========+=============================================+
| 1 | WITH | Model reference is evaluated first. |
+-------+----------+---------------------------------------------+
| 2 | brackets | Brackets evaluate before grouping keywords. |
+-------+----------+---------------------------------------------+
| 3 | AND | AND grouping evaluates before OR grouping. |
+-------+----------+---------------------------------------------+
| 4 | OR | Evaluates last. |
+-------+----------+---------------------------------------------+
A number of attributes from the meta data of a model can also be
searched:
* ``__device_pkid``: if a device pkid is known, then for example:
``device/cucm/Line WITH __device_pkid IS 55c32b59a6165451e04f392a``
* ``pkid``: if a pkid is known, then for example:
``data/CallManager WITH pkid IS 55c32b59a6165451e04f392a``
* ``tags`` (can also use "tag"): if the tag name is known, then
for example:
::
((data/FieldDisplayPolicy WITH tag IS feature_tag_add_customer) AND
(data/FieldDisplayPolicy WITH tags IS applicationendtoend))
.. note::
Only tags that are written in lower case are searchable.
.. |search-syntax| image:: /src/images/search-syntax.png
.. |VOSS-4-UC| replace:: VOSS-4-UC
.. |Unified CM| replace:: Unified CM