close

Filter

loading table of contents...

Content Server Manual / Version 2401

Table Of Contents

3.13.3.7 Query

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 content items into the new syntax and execute them.

Note

Note

For more details about the query syntax and for more examples see Section 5.7, “Query Service” in Unified API Developer Manual.

usage: cm query -u <user> <other options>  [ -f <default|id|path|uuid> ] [
          -xl <limit> ] [ -R ] [ -l <limit> ] [ <id1>... | -I <id1>... |
          -U <uuid1>... | -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>)
 -f,--format <default|id|path|uuid>   output format; possible options:
                                      'default' for the default format;
                                      'id' to only print the ID; 'uuid' to
                                      only print the UUID; 'path' to
                                      output the content path, possibly
                                      prefixed by '*' for deleted contents
 -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; you will be
                                      prompted for password if not given
 -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,--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 <arg>             limits the query results for
                                      executed transformed legacy queries
                                      (use -1 for unlimited); by default
                                      uses same value as denoted by '-l'
...

Example 3.44. 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 linked by OR.
-vq <query> Content Selection Version Query to locate contents. For contents see -cq. Parameter can be used multiple times. Results will be linked by OR.
-R Content Selection Add contents from recycle bin. 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 linked by OR.
-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 linked by OR.
-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 content item 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.
-U <UUID> Content Selection Select contents via UUID. This is an alternative if you want to mix UUIDs with for example content queries. Parameter can be used multiple times. Results will be linked by OR.
-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 linked by OR.
<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 linked by OR.
-l <limit> Content Selection Limit the number of selected contents to the given value. Default is unlimited.
-f <default|id|path|uuid>

Chooses a suitable output format. While default applies to the default multi-column output, other formats output single values per line, suitable for piping to subsequent commands, for example.

id outputs the ID, path outputs the path of the related content item, uuid outputs the UUID.

Table 3.48. 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.45. 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.46. 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.47. 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.49. Identifiers and literals


Example: Combine cm query with cm dump using --format

You can use the --format option to create output that can be used as input for other cm tools, e.g., you could query for contents and then dump the resulting contents like this (example for Bash):

bin/cm query \
  --url ... \
  -cq "BELOW PATH '/Sites/Chef Corp.'" \
  --format id |\
  xargs bin/cm dump \
  --url ...

Example 3.48. Combine cm query with cm dump using --format


Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.