The query tool can be used to start a synchronous, structured query against the content repository. It's analogous to the query used within the editors but you can create more sophisticated queries with the query tool. You can also transform old queries from Query documents into the new syntax and execute them.
![[Note]](../common/images/note.png) | Note |
|---|---|
For more details about the query syntax and for more examples see Section 5.5, “Query Service” in CoreMedia Unified API Developer Manual. |
usage: cm query -u <user> <other options> [ -xl <limit> ] [ -R ]
[ -l <limit> ]
[ <id1>... | -I <id1>... | -t <path1>... |
-cq <query1>... | -vq <query1>... ]
available options:
-cq,--contentquery <query> query/queries to select contents
-d,--domain <domain name> domain for login (default=<builtin>)
-I,--id <id> id(s) to select content objects
-l,--limit <limit> limits the number of content objects
to select, negative for unlimited
which is also the default
-m,--transform transform a legacy query given by -q
into a UAPI query
-p,--password <password> password for login
-q,--query <query> query string; deprecated for
UAPI-queries, use contentquery or
versionquery instead
-R,--recyclebin include contents from recycle bin
-t,--path <path> path(s) to select content objects
-u,--user <user name> user for login (required)
-url <ior url> url to connect to
-v,--verbose enables verbose output
-vq,--versionquery <query> query/queries to select versions
-x,--execute transform a legacy query into a UAPI
query and execute it, implies -m
-xl,--executelimit <limit> limits the query results for
executed transformed legacy queries
(use -1 for unlimited); by default
uses same value as denoted by '-l'
...
Example 3.28. Query usage
| Parameter | Description |
|---|---|
-cq <query> |
Content Selection
Content Query to locate contents. For versions see -vq.
Parameter can be used multiple times. Results will be ORed.
|
-vq <query> |
Content Selection
Version Query to locate contents. For contents see -cq.
Parameter can be used multiple times. Results will be ORed.
|
-R |
Content Selection
Add contents from recyclebin. Could also be done via -cq.
|
-I <id> | Content Selection Select content objects via explicit id. This is an alternative if you want to mix explicit ids with for example content queries. Parameter can be used multiple times. Results will be ORed. |
-q <query> |
The query string. Especially to be used for transforming legacy queries at command line.
For selection of contents the parameters -cq and
-vq are recommended.
Parameter can be used multiple times. Results will be ORed.
|
-e |
If set, the query specified by -q searches for all versions of the
content items.
Deprecated: Use -vq instead. |
-xl <limit> | Limit the number of results for executing transformed legacy queries. If not given
defaults to -l. |
-m | With the -m option you can transform legacy queries (according to
the coremedia-query.dtd DTD) into UAPI queries (according to the syntax below). You can
specify the legacy query directly with the -q option or you can select
via id, path or for example -cq contents of content type Query whose legacy
query will then be transformed at command line (the Query document itself is left untouched).
If you want to see the results of the query in addition to this you can add the
parameter -x.
|
-x | Like -m, additionally executes the transformed query.
Implies -m. |
-t <path> | Content Selection Paths to be added to the result or path to Query content items to be transformed and possibly executed. Parameter can be used multiple times. Results will be ORed. |
<ids> |
Content Selection
IDs to be added to the result or id of Query content items to be transformed and possibly
executed. If mixing with other content selection parameters it is recommended to explicitly
use the parameter -I.
Parameter can be used multiple times. Results will be ORed.
|
-l <limit> | Content Selection Limit the number of selected contents to the given value. Default is unlimited. |
Table 3.40. Parameters of the query utility
The following example shows the output of a query which searches for all content items below the
/MenuSite/Fish folder:
cm query -u admin -p admin -cq "BELOW PATH '/MenuSite/Fish'"
The result shows the ID, the type and the path/name of the found content items.
coremedia:///cap/content/210 <Picture>
/MenuSite/Fish/SoleCitrus_pic
coremedia:///cap/content/212 <Picture>
/MenuSite/Fish/SalmonCitrus_pic
coremedia:///cap/content/216 <Picture>
/MenuSite/Fish/FreshCod_pic
coremedia:///cap/content/218 <Dish>
/MenuSite/Fish/SoleCitrus
coremedia:///cap/content/222 <Dish>
/MenuSite/Fish/SpicyTrout
coremedia:///cap/content/716 <Dish>
/MenuSite/Fish/CarpDish
coremedia:///cap/content/718 <Dish>
/MenuSite/Fish/troutmeal
Example 3.29. Result of a query
The following example transforms the default query of user johndoe into a UAPI query:
cm query -u admin -p admin -m -t "/Home/johndoe/My Query"
Note, that the name of the default query content item is locale specific. For German editors it is "Meine Recherche". The result shows the transformed query without executing it.
Legacy query: <QUERY VERSION="6" LIMIT="50"><DOCUMENTTYPES VALUE="Document_"> <AND><AND><BOOLEAN VALUE="true"/><ISDESCENDANTOF VALUE="311"/> </AND><LATEST/></AND></DOCUMENTTYPES></QUERY> UAPI query: TYPE "Document_": (BELOW ID 'coremedia:///cap/content/311') AND ((version=workingVersion OR version=checkedInVersion)) LIMIT 50
Example 3.30. Transformation of a legacy query
On the command line, the query string will usually be surrounded by quotes, so that the shell interprets it as a single argument. You may also have to escape quote characters inside the query string.
The next code block shows the formal definition of the UAPI query language using EBNF:
query ::=
conditional_expression [ order_by ] [ limit ]
;
order_by ::=
ORDER BY order_entry { "," order_entry }
;
limit ::=
LIMIT numeric_literal
;
order_entry ::=
property [ ASCENDING | ASC | DESCENDING | DESC ]
;
conditional_expression ::=
TYPE ["="] type { "," type } [":" conditional_expression]
| conditional_expression OR conditional_expression
| conditional_expression AND conditional_expression
| NOT conditional_expression
| "(" conditional_expression ")"
| BELOW content
| REFERENCES content
| property REFERENCES content
| REFERENCED BY version
| property IS [NOT] NULL
| comparison_expression
| contains_expression
| value_expression
;
type ::=
identifier
;
comparison_expression ::=
value_expression comparison_operator value_expression
;
comparison_operator ::=
"=" | ">" | ">=" | "<" | "<="
;
contains_expression ::=
property CONTAINS literal_expression
| property CONTAINS EXACT literal_expression
| property CONTAINS PREFIX literal_expression
| property CONTAINS STEM literal_expression
;
value_expression ::=
property
| literal_expression
;
property ::=
implied_property
| identifier
;
content ::=
literal_expression
;
version ::=
literal_expression
;
literal_expression ::=
string_literal
| numeric_literal
| boolean_literal
| DATE string_literal
| PATH string_literal
| USER string_literal
| ID string_literal
| input_parameter
;
boolean_literal ::=
TRUE
| FALSE
;
Example 3.31. EBNF definition of the query language
The next table shows the definitions of the identifiers and literals of the query language.
| Item | Example | Description |
|---|---|---|
| Identifier |
Article "parent" | Identifiers consist of Java identifier characters. Where the name of an identifier collides with a keyword or an implied property, the identifier can be enclosed in double quotes to preserve its meaning as an identifier. |
| String literal | 'Title text' | String literals are delimited by single quotes. A single quote inside a string literal is represented by two successive single quotes. |
| Numeric literal | 1234 | Numeric literals conform to Java syntax. Essentially, a numeric literal is a sequence of digits, optionally preceded by a minus sign. |
| DATE literal | '2004-09-08T13:47:07-02:00' | The string used for DATE literals has to be of the form
recognized by the DateConverter class (see the Javadoc). |
| PATH literal | '/MenuSite/Fish' | PATH literals denote a content by giving its path, beginning at the
root folder. It is an error if no content exists at the given path. |
| USER literal |
'admin' 'paul@msad' | USER literals denote a user name and a domain name separated by a
"@" character. If the domain name is empty, the "@" character may be omitted.
|
| ID literal | 'coremedia:///cap/content/1' | ID literals denote a content, version or user by giving its ID, as returned
by CapObject.getId(). |
Table 3.41. Identifiers and literals
 |  |  |
 |