Use REST APIs for Content Search

Oracle Content Management REST APIs allow you to search published or managed content (content items and digital assets) by fetching items matching a search query submitted to the /items resource.

Search Query Operators

Search Query Scopes

• /content/published/api/v1.1/items

  The search query scope in the REST API for Content Delivery is a publishing target which is specified by its channel token. A channel token must be provided as either a query parameter or a request header.

• /content/management/api/v1.1/items

  The search query scope is controlled by editorial permissions granted to the API client users. A search query will fetch only items that users can see based on the repository membership and granular editorial permissions on assets in it.

If the publishing target that you selected for a request to the REST API for Content Delivery is secure (i.e., assets are published to a secure publishing channel), the search request that you send requires using OAuth for authorization. Any search request that you send to the REST API for Content Management requires using OAuth for authorization.

Search Query Expressions

Item searches in the REST API for Content Management and the REST API for Content Delivery share query parameters and use the same syntax for building a search query expression. Therefore, a single term, the Search API is used below to refer to item searches in either REST API.

The Search API allows you to specify a search query expression as a value of the q parameter in requests submitted to the /items resource. The Search query expression syntax supports various operators to define match conditions (e.g., eq, ne, co, or sw) plus AND, OR, and () operators to combine match conditions into a complex query expression that match the field values within a single asset type or across multiple types. Extra search query request parameters allow you to control the number of matching items to be fetched, how matching items are paginated and sorted, or what data fields are returned for matching items. Keep in mind that regardless of the search scope and expression, the maximum page size that the API can return matching items is limited to 500.

Two generic forms of search queries are supported in the Search API

• Query within an asset type: Query expression requires you to specify an asset type and allows references to both standard and user-defined data fields of this type in query conditions.

  For example: /api/v1.1/items?q=(type eq "Employee" AND fields.role eq "Senior Developer"). Here, the role is a field of type Employee.

• Query across asset types: Depending on how a query expression is formulated, the Search API supports two types of cross-type queries:
  • Global query on standard fields: Query expression allows you to specify more than one asset type using parentheses () or no type at all. Such query is treated as a global (untyped) query with the ability to reference standard fields only in query conditions.

    For example: /api/v1.1/items?q=(name eq "John" or description co "John" and (type eq "t1" or type eq "t2"))

  • Query across specific types: Query expression allows you to specify more than one asset type using curly brackets {}. Such query is treated as a generic query across specified asset types with the ability to reference both standard and user-defined fields in query conditions. For more information, see Search Across Types.

    For example: /api/v1.1/items?q=(name eq "John" and {type eq "t1" and fields.ud1 eq "ud1val"} or {type eq "t2" and fields.ud2 eq "ud2val"}

The standard data fields that are supported in asset types

• In Management API:

  id, type, name, description, typeCategory, slug, translatable, language, createdBy, createdDate, updatedBy, updatedDate, repositoryId, channels, collections, status, tags, isPublished, languageIsMaster, taxonomies

• In Delivery API:

  id, type, name, description, typeCategory, slug, translatable, language, createdDate, updatedDate, taxonomies

While querying using standard fields in either search query form, the various data fields are treated differently:

Data Fields	Data Type
name, description, type, typeCategory, slug, language, status	text data type (single valued)
id, repositoryId	reference (single valued)
createdDate, updatedDate	datetime (single valued)
translatable,isPublished, languageIsMaster	boolean (single valued)
collections, channels, tags, taxonomies, suggestedTaxonomies	reference data type (multi valued)

In either search query form, it is possible to search by matching items anywhere (i.e., matching any standard or user-defined data field) by specifying a match criteria via the query parameter default on request. Such a criterion is treated as a generic query that matches values of the items across all fields that are indexed as an aggregate text data. For example:

• /api/v1.1/items?default="coffee"
• /api/v1.1/items?q=(type eq "Employee")&default="senior"

Find more details about the following:

• Search operators and query parameters that are supported in the Search API.
• Two-level deep search and related options that are supported for order matching items by a reference field.
• Search for custom fields across type and related to that order by parameter.
• Getting dynamic asset counts on a taxonomy category and using this API to support faceted search.

Stop words (words to be filtered out in your search)

The following English stop words will be filtered out for default search and typed anyField search:

a, an, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, or,such, that, the, their, then, there, these, they, this, to, was, will, with.

Search Operators

Searches in the REST API for Content Management or REST API for Content Delivery allow you to create search query expressions using a rich set of operators to define field match conditions plus, AND, OR, and () operators to combine them into a complex query expression that can match the field values within a single asset type or across multiple types. The table below lists search query operators that are currently supported in the Search API.

Operator	Example	Supported Data Types	Description
eq	?q=(name eq "John") ?q=(type eq "DigitalAsset") ?q=(type eq "Employee" and fields.DOB eq "1994/09/26T16:23:45.208") ?q=(type eq "File" and fileextension eq "docx") ?q=(taxonomies.categories.id eq "B9F568DC43C54803AC76012783FA5101") ?q=(taxonomies.categories.name eq "cars")?q=(taxonomies.categories.apiName eq "cars-unique") ?q=(taxonomies.categories.nodes.id eq "B9F568DC43C54803AC76012783FA5101") ?q=(taxonomies.categories.nodes.name eq "cars")?q=(taxonomies.categories.nodes.apiName eq "cars") ?q=(suggestedTaxonomies.categories.id eq "B9F568DC43C54803AC76012783FA5101")	text, reference, number, decimal, boolean, datetime.	The equals operator eq matches the exact value supplied in the query. This operator is not applicable to multivalued data types. The value provided with this operator is not case-sensitive except for standard fields. This operator considers even special characters in the value.
ne	?q=(name ne "John")	text, reference, number, decimal, boolean, datetime.	The not equals operator ne matches items that do not match the exact value supplied in the query. This operator is not applicable to multivalued data types. The value provided with this operator is not case-sensitive except for standard fields. This operator considers even special characters in the value. The ne operator can be used with queries on user-defined fields within an asset type. But a cross-type query cannot include search terms on user-defined fields.
co	?q=(type eq "Employee" AND name co "john alex") ?q=(type eq "Car" AND fields.features co "manual") ?q=(taxonomies.categories.name co "red") ?q=(taxonomies.categories.nodes.name co "car")	text, reference, number, decimal, datetime, largetext	The contains operator co matches every word given in the criteria. The words are formed by splitting the value by special characters. It gives the results that have at least one of the words (in this example, john or alex or both). This operator does not consider special characters in the value while searching. This operator does not search for stop words. This operator is applicable to text, largetext in case of single-valued attributes, whereas for multivalued attributes, it is applicable to text, reference, number, decimal, datetime, largetext. To understand the possible datetime formats, refer to Supported Date and Time Formats. The value provided with this operator is not case-sensitive.
nc	?q=(name nc "john alex")	text, reference, number, decimal, datetime, largetext	The not contains operator nc matches items that would not match a co operator with the same criteria.
sw	?q=(type eq "Employee" AND name sw "Joh") ?q=(type eq "Employee" AND fields.city sw "Los") ?q=(taxonomies.categories.name sw "cat") ?q=(taxonomies.categories.nodes.name sw "red")	text	The starts with operator sw matches only the initial character values given in the field condition. This operator is not applicable to multivalued data types. The value provided with this operator is not case-sensitive.
ge	?q=(type eq "Employee" AND fields.age ge "40") ?q=(type eq "DigitalAsset" AND updatedDate ge "20171026")	number, decimal, datetime	The greater than or equal to operator ge matches only numeric and datetime values. To understand the possible datetime formats, refer to Supported Date and Time Formats. This operator is not applicable to multivalued data types.
le	?q=(type eq "Employee" AND fields.weight le "60.6")	number, decimal, datetime	The less than or equal to operator le matches only numeric and datetime values. To understand the possible datetime formats, refer to Supported Date and Time Formats. This operator is not applicable to multivalued data types.
gt	?q=(type eq "Employee" AND fields.age gt "20")	number, decimal, datetime	The greater than operator gt matches only numeric and datetime values. To understand the possible datetime formats, refer to Supported Date and Time Formats. This operator is not applicable to multivalued data types.
It	?q=(type eq "Employee" AND fields.age lt "20") ?q=(type eq "Employee" AND createdDate lt "1994/09/26T16:23:45.208")	number, decimal, datetime	The less than operator lt matches only numeric and datetime values. To understand the possible datetime formats, please refer to Supported Date and Time Formats. This operator is not applicable to multivalued data types.
mt	?q=(type eq "Car" AND fields.review mt "petrol 20KMPL") ?q=(type eq "Employee" AND name mt "Jo?n") ?q=(type eq "Employee" AND name mt "Jo*") ?q=(type eq "Employee" AND fields.role mt "senior*")	text, largetext	The phrase query or proximity search matches operator mt enables you to find words that are within a specific distance to one another. Results are sorted by the best match. It is useful for searching content items when values provided in the criteria "petrol 20kmpl" of the query need to match content that may contain "petrol fuel mileage runs 20KMPL in the speed way". The matches operator can use a wildcard (? or *) to match multiple characters within the given value. This operator is applicable to both single-valued and multivalued data types. This operator does not search for stop words. The value provided with this operator is not case-sensitive. To match exact phrases, enclose search terms in double quotes. Enclosing double quotes will be treated as part of the search term in all other contexts.
sm	?q=(type eq "Employee" And fields.city sm "Rome")	text, largetext	This operator sm allows searching for values that sound like specified criteria - also called fuzzy search, which uses, by default, a maximum of two edits to match the result. "Rome" is similar to "Dome". This operator is applicable to both single-valued and multivalued data types. The value provided with this operator is not case-sensitive.
AND	?q=(type eq "Employee" AND name eq "John" AND fields.age ge "40")	-NA-	The AND operator, can be used to put an AND condition between multiple query conditions. This takes precedence over OR.
OR	type eq "Employee" AND name eq "John" OR fields.age ge "40"	-NA-	The OR operator can be used to put an OR condition between multiple query conditions.
( )	?q=(type eq "Employee" AND (name eq "John" AND fields.age ge "40")) ?q=(type eq "Employee" AND ( (name eq "John" AND fields.age ge "40") OR fields.weight ge 60))	-NA-	The parenthesis, enclosing operator ()can be used to group the conditions in the criteria. This takes highest precedence, followed by AND and then by OR.

Search Queries

When you are creating a search query expression, take into account the following extra details about using operators in a specific search query or with a specific data type that are provided in the table below.

Query	Description
Type specific query	This query always uses only the eq operator; eq works with case-sensitive type names. Multitype query is supported, such as ?q=(type eq "Employee" OR type eq "Address"), however, it will be a query across types. Example: ?q=(type eq "Employee" OR type eq "DigitalAsset") is supported because of a single type search.
Date query	The date query is a special type of query because of various date formats associated with it. All the datetime values in the query are assumed to be in the UTC time zone only, unless the offset is added in the ISO 8901 format. The query results will always be in the UTC timezone format for all datetime fields. Fields with the data type datetime should use the operators ge, gt, le, lt for a range query and use eq for an equals match. Supported Date and Time Formats describes date / datetime formats that are accepted in a date query. Example:Query Products by the manufactureDate (datetime) field using the ge operator. https://{cecsdomain}/content/management/api/v1.1/items?q=(type eq "Product" AND fields.manufactureDate ge "1989-03-26"). The given date format is YYYY-MM-DD .
Decimal values query	The decimal number query is supported up to three digits after decimal points, and the rest of the digits are ignored. https://{cecsdomain}/content/management/api/v1.1/items?q=(type eq "Product" AND fields.price ge 425.3214), will return all the products where the price is greater than or equal to 425.321.
Large text data type query	Fields with the data type largetext are not stored. So the query result cannot return its value. But the field value can be used in a query condition.
Generic query	The generic query is a default search query, which can be used when the user can search by value only without using any field name or operators. Internally, a generic search uses the co operator. This query does not support wildcard characters. This query does not search for stop words. Example: ?q=(type eq "Employee")&fields=all&default=John. This will return the search results for the Employee type where the value John matches the field name, description, or any user-defined fields. Example: ?q=(type eq "Article")&default=skating. This will return the search results for the Article type where the value skating matches the field name, description, or any user-defined fields.
Id query	This is a search query that uses the Id attribute. Example: ?q=(type eq "Employee" AND id eq "COREAF29AC6ACA9644F9836E36C7B558F316"). The value of Id belongs to the item being queried, here it is the Id of type Employee. It is possible to include multiple item Ids in the query expression. Example: ?q=(type eq "Employee" AND (id eq "COREAF29AC6ACA9644F9836E36C7B558F316" OR id eq "COREAF29AC6ACA9644F9836E36C7B558F987")).
Category query	This query searches items categorized with given category Id, category name, category apiName, category node Id, category node name, or category node apiName attributes. Example: ?q=(taxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489") The value of taxonomies.categories.id belongs to the category assigned to items being queried. It is possible to include multiple category Ids or names in the query expression. Example: ?q=(taxonomies.categories.name co "cars" OR taxonomies.categories.name sw "red") Example: ?q=(taxonomies.categories.apiName eq "All-furnitures") The value of taxonomies.categories.apiName belongs to the category assigned to items being queried. It is possible to include multiple category apiName values in the query expression. Example: ?q=(taxonomies.categories.nodes.id eq "9E1A79EE600C4C4BB727FE3E39E95489") The value of taxonomies.categories.nodes.id belongs to any node of categories assigned to items being queried. It is possible to include multiple category node Ids or node names in the query expression. Example: ?q=(taxonomies.categories.nodes.name co "cars" OR taxonomies.categories.nodes.name sw "red") Example: ?q=(taxonomies.categories.nodes.apiName eq "All-furnitures" OR taxonomies.categories.nodes.apiName eq "all-accessories") The value of taxonomies.categories.nodes.apiName belongs to any node of categories assigned to items being queried. It is possible to include multiple category node apiName values in the query expression.
Suggested category query	This query searches items that could be categorized into a given category with category Id, rejected status, and language. Only one category Id can be used for filtering at a time; repositoryId is mandatory when filtering on suggestedTaxonomy. The default status is not rejected. When no language is specified, items from all languages are returned. Example: ?q=(repositoryId eq "86E125F3D78B409EBF61737636599FE1" AND suggestedTaxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489") Lists all the items from all languages that are suggested for the given category Id for the given repository and not rejected. Example: ?q=(repositoryId eq "86E125F3D78B409EBF61737636599FE1" AND suggestedTaxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489" AND suggestedTaxonomies.categories.isRejected eq "false") Lists all the items from all languages that are suggested for the given category Id for the given repository and not rejected. Example: ?q=(repositoryId eq "86E125F3D78B409EBF61737636599FE1" AND suggestedTaxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489" AND suggestedTaxonomies.categories.isRejected eq "false" AND language co "en-US") Lists all the items from the given language that are suggested for the given category Id for the given repository. Example: ?q=(repositoryId eq "86E125F3D78B409EBF61737636599FE1" AND suggestedTaxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489" AND suggestedTaxonomies.categories.isRejected eq "true" AND language co "en-US") Lists all the items from the given language that are previously rejected for the given category Id for the given repository.
Lock status query	This query searches items by locked status. Example:?q=lockInfo.status eq "locked" Lists all the items that are in locked status. Example: ?q=lockInfo.status eq "unlocked" Lists all the items that are in unlocked status. Example: ?q=lockInfo.lockedBy eq "userName"&fields=lockInfo Lists all the items that are locked by the user specified and displays the lock information in results.
Reference field query	This search query uses reference attribute. Example:?q=(type eq "Employee" AND fields.department eq "COREAF29AC6ACA9644F9836E36C7B558F412"). The value of department belongs to the Id of an item of type department.
Match text in any field query	The query searches for assets within a type or across specific types. The search in any field and binary file’s text is supported by using query syntax that matches an asset anywhere. This query does not search for stop words. Example: ?q=(type eq "Employee" AND (anyField co "John Smith" and fields.address.state eq "CA")) Example: ?q=(type eq "cdt1" AND (anyField co "John Smith" and fields.address.state eq "CA")) Example: ?q=(type eq "DigitalAsset" AND anyField co "John Smith") Use query operators that are supported by the query syntax: CO (contains), MT (phrase match), NC (not contains). Note: The MT operator cannot be used in an anyField query to search for values in a number or decimal field.
Match text in a binary file query	The query does typed search to match the text in the binary file of the digital asset. The search in the binary file’s text in the digital assets is supported by using metadata.extractedText parameter in the search query within a type or across specific types. Example: ?q=(type eq "File" AND metadata.extractedText co "Employee") Example:?q=({type eq "cdt1" AND metadata.extractedText mt "installed"} or {type eq "cdt2" AND metadata.extractedText mt "installed"}) Use query operators that are supported by the query syntax for Text data type: CO (contains), MT (phrase match), NC (not contains).

Supported Date and Time Formats

The table below describes DATE and DATETIME formats that are accepted for use in a query condition that uses the date data field:

Format	Example
YYYY-MM-DD	1989-03-26
YYYY/MM/DD	1989/03/26
DD-MM-YYYY	26-03-1989
DD/MM/YYYY	26/03/1989
YYYY-MM-DD''T''hh:mm:ss	1989-03-26T18:32:38
YYYY/MM/DD''T''hh:mm:ss	1989/03/26T18:32:38
DD-MM-YYYY''T''hh:mm:ss	26-03-1989T18:32:38
DD/MM/YYYY''T''hh:mm:ss	26/03/1989T18:32:38
YYYY-MM-DD''T''hh:mm:ss.SSS	1989-03-26T18:32:38.840
YYYY/MM/DD''T''hh:mm:ss.SSS	1989/03/26T18:32:38.840
DD-MM-YYYY''T''hh:mm:ss.SSS	26-03-1989T18:32:38.840
DD/MM/YYYY''T''hh:mm:ss.SSS	26/03/1989T18:32:38.840
YYYYMMDD	19890326
YYYYMMDDhhmmss	19890326183238
YYYYMMDDhhmmssSSS	19880326183238840
YYYY-MM-DD''T''hh:mm:ss.SSS+/-HH:mm	1989-03-26T18:32:38.840+05:30
YYYY-MM-DD''T''hh:mm:ss+/-HH:mm	1989-03-26T18:32:38+05:30

Search with the Querytext Parameter

You can use the querytext parameter of the Search Folders or Files APIs in the REST API for Documents to take advantage of string search, tag search, and custom metadata field search at the same time.

The querytext search string is available in the Search Folders or Files and the Search Folders or Files Under Specific Folder ID endpoints, to match folder or file names and allow for tag search or custom metadata field search as well. You can use querytext to search an entire directory tree in your home (self) directory as well as shared folders.

To set up querytext searches with the REST APIs:

1. Create files and folders, and add tags to them for string searches.

   Tags currently support only CONTAINS.

   1. Plan where you will place each tag because tags are inherited from parent folders.

   2. Set tags, add tags, or remove tags with the following APIs: Set Folder Tags, Edit Folder Tags, Set File Tags, and Edit File Tags

2. Add metadata collections.

   1. As an administrator, create global collections (personal collections are not supported as indexed collections).

   2. Determine which fields you will need to support the search, and call APIs in the metadata resource to index those fields.

      There is a limit of 100 fields to be indexed. You cannot remove fields from the index. The search is done on Favorite shared folders first and then other shared folders, up to 100. You may want to designate some folders as Favorites before searching, to ensure better search results.

   3. Metadata fields of an integer type cannot be searched as a number.

   4. You can search metadata fields of a Date type in a search API from the REST API for Documents. This enables you to search for exact date matches or for a range of dates (that is, files where the date falls between a specific start date and a specific end date).

3. Build your query.

   1. Use a search strings in the querytext parameter of the Search Folders or Files and the Search Folders or Files Under Specific Folder ID endpoints to search your folder and file names, tags, and indexed metadata fields.

      For examples of tags and custom metadata searches, see the descriptions of the endpoints in the REST API for Documents.

   2. Search queries require URL encoding of the single-quotation-mark character ( ') into %60. For example, Collection1.field1<CONTAINS>'myValue' turns into Collection1.field1<CONTAINS>%60myValue%60.

   3. Start with simple queries to validate that your conditions do indeed find results.

   4. You can build more complex queries by combining parentheses, <AND> clauses, and <OR> clauses.

Set Up Searches on Metadata Fields

Set up searchable metadata fields with the Metadata Collection resource of the REST API for Documents. Then you can run text searches with custom fields.

To search metadata fields:

1. Sign in to Oracle Content Management as an administrator and create a metadata collection.

   See Metadata Collection Resource.

2. As an administrator, check which metadata fields are already searchable with the Get Searchable Metadata Fields endpoint, so you can determine how many fields you can add to the search index.

   This REST API call retrieves all metadata fields currently available for searching content, The result list includes all metadata fields prefixed with their respective global metadata collection for the tenant. Each tenant is limited to 200 searchable fields.

3. Use the Set Searchable Metadata Fields endpoint of the REST API for Documents to specify metadata fields that are searchable.

   After you reach 200 fields, you cannot index new fields to become searchable. Currently, fields cannot be removed from the search index unless the metadata collection and/or field are deleted from the system. When a collection and/or field are deleted, all the existing metadata information previously set will be lost (not recoverable). After this, new fields will be allowed to become searchable up to the 200 fields limit.

For custom metadata searches, the REST API for Documents supports only text searches using CONTAINS. It does not support numeric or date searches. For example, custom metadata fields created through the web user interface are not searchable because they are numeric or date type fields.

For more information about these endpoints and examples of using them, see "Set Searchable Metadata Fields" and "Get Searchable Metadata Fields" under "Metadata Collection" in REST API for Documents.

Search Request Parameters

In addition to q or default parameters, a search request submitted to the /items resource allows you to use other request parameters to control number of items or item fields returned in response. The tables below provide details about requests accepted by the REST API for Content Delivery and REST API for Content Management.

REST API for Content Delivery

Query Parameter	Type	Description
channelToken	string	Channel token of the publish target. A channel token must be provided as either a query parameter or a request header.
default	string	Default search query expression that matches the values of items across all fields.
fields	string	The fields parameter is used to control the returned fields and values in the queried item. This parameter accepts a comma-separated list of field names or all. All the user-defined field names should be provided with the fields prefix and followed by a period (.). These fields will be returned for each queried item. As all the field names are case-sensitive, users must provide the correct field names in the search query. When fields is specified as all (case-insensitive), in case of a type-specific query, all the standard fields, and user-defined fields except largetext, json, location datatype are returned for each queried item, whereas in case of a query across all types, only all standard fields are returned. The standard field Id and type are always returned in the response and cannot be filtered out. This parameter is optional in the query and by default query result shows only Id, name, description, and type in the response. Any incorrect or invalid field name given in the query will be ignored. In the context of a brace style cross-type query, type-specific fields may be specified using the syntax name,{typename1:fields.userdefinedfieldname1,fields.userdefinedfieldname2},{typename2:fields.userdefinedfieldname1}. In the preceding example, all items of the type typename1 will have fields - name, userdefinedfieldname1, and userdefinedfieldname2, while all items of the type typename2 will have fields - name, userdefinedfieldname1. If the cross-type query does not resolve to types referenced in the typed fields clause(s), an error will be thrown. Example: ?q=(type eq "LocationType")&fields=fields.state,fields.country,updatedDate This returns Id, type, state, country, updatedDate in the search results for a LocationType with state and country fields. Example: ?q=(type eq "LocationType")&fields=all This will return all standard fields and all user-defined fields except largetext, json, location data types Example: ?fields=all This will return only standard fields (Id, type, typeCategory, name, description, slug, language, createdDate, updatedDate, taxonomies, renditions) since the type field is not used in the search query (acts as a global query) Example: ?fields=name,createdDate This will return only standard fields (such as Id, name, createdDate, and type) since the type field is not used in the search query (acts as a Global query) Default Value: name,description,slug,language,translatable,createdDate,updatedDate
limit	integer(int32)	Number of rows to return. The default value is 100.
links	string	Accepts a comma-separated list of rel (relation) links, which the client requires in the results. By default, all the applicable links in a resource are included in the response. Possible values are: self, canonical, describedby, first, last, prev, next. Example: links=self,canonical will only return the links with the rel property, self, or canonical.
offset	integer(int32)	Start index of response rows. The default value is 100.
orderBy	string	The orderBy parameter is used to control the order (ascending or descending) of queried items. This parameter is optional in the query and by default the results are sorted in the descending order of updatedDate. This parameter accepts featured() or field names separated by a colon (:), which the user wants to sort the results and sort order. Multiple sort orders are separated by semicolon (;). Format: orderBy={fieldName1}:{asc/desc};{fieldName2}:{asc/desc} Note: asc stands for ascending and des for descending. asc and des are always in lower case. In a type specific query, field names can be: name, createdDate, updatedDate (standard fields), or user-defined fields (single-valued data types: number, decimal, datetime, text). All the user-defined field names should be provided with prefix fields and followed by a period (.). In the context of a cross-type search, this parameter can also have a typed section and takes the form {typename1:fields.userdefinedfieldname1:asc|desc};{typename2:fields.userdefinedfieldname1:asc|desc}. The orderBy parameter only supports one order by field per set of matching braces. The sort order is optional and by default it is ascending. Any incorrect or invalid field name given in the query will be ignored. When featured() is given, the results are sorted by the relevance of the items to the applied filter. The orderBy parameter also supports the following: Sorting by a two-level field. If there is a two-level sort field, then it can be the only sort field in the orderBy parameter. Sorting assets using user-defined text field or an attribute in JSON data stored in JSON field (embedded content) on assets in a two-level search. Note: The two-level sorting does not work on multiple value fields, so this does not work on multiple text fields. The two-level sorting works on any array attributes on JSON fields because JSON fields can only be a single value field. Sorting by taxonomy root categories and sub-categories of a root category. The additional sorting parameters are as follows: taxonomies.shortName["short name of taxonomy"]:{asc/desc}; taxonomies.categories.nodes.name["short name of taxonomy"|"taxonomy name","category1","category2","category3"] where category1, category2, category3, etc. are sub-categories of a given taxonomy "taxonomy name". Sorting by an attribute in JSON data stored in JSON field on assets. Example: orderBy=name:asc Returns all the items in the ascending order of name. Example: orderBy=updateDate:asc Returns all the items in the ascending order of updateDate. Example : orderBy=fields.age:des Returns all the items in the descending order of age. Example: orderBy=fields.age Returns all the items in the ascending order of age. Example : default=apples&orderBy=featured() Returns all the items sorted by the relevance of the items to the apples. Example : orderBy=fields.blogauthor.authorage Returns all the items in the ascending order of age of the author referred by referenced field "blogauthor". Example: orderBy=fields.blogauthor.fields.authorage&twolvl_v1_1=true Returns all the items in the ascending order of age of the author referred by referenced field "blogauthor". Example: orderBy=taxonomies.shortName["loc"];taxonomies.categories.nodes.name["loc"|"Location","emea","china","industry"];taxonomies.categories.nodes.name["loc"|"Location","americas","brazil","industry"] Returns all the items sorted in the ascending order of root category of "loc", sub-categories of category whose path is /Location/emea/china/industry, sub-categories of category whose path is /Location/americas/brazil/industry. Example: orderBy=fields.<text_field_name>:asc Returns all the items sorted in the ascending order using the user-defined text field. Example: orderBy=fields.<json_field_name>.value.<attribute_name>:asc Returns all the items sorted in the ascending order using an attribute in JSON data stored in JSON field (embedded content) on assets. Example: orderBy=fields.<ref_field_name><text_field_name>:asc Returns all the items sorted in the ascending order using two-level reference to the user-defined text field. The example uses the compatibility mode of the two-level search. Example: orderBy=fields.<ref_field_name>.fields.<text_field_name>:asc&twolvl_v1_1=true Returns all the items sorted in the ascending order using two-level reference to the user-defined text field. The example uses the two-level mode of the two-level search.
q	string	This parameter accepts a query expression condition that matches the field values. Many such query conditions can be joined using AND/OR operators and grouped with parentheses. The value of query condition follows the format of {fieldName} {operator} "{fieldValue}". In the case of a query across type, the field names are limited to standard fields (Id, type, name, description, typeCategory, slug, language, createdDate, updatedDate, taxonomies). However in the case of a type-specific query, the field names are limited to standard fields and user-defined fields (except fields of largeText data type). The only values allowed in the operator are eq (Equals), co (Contains), sw (Startswith), ge (greater than or equals to), le (less than or equals to), gt (Greater than), lt (less than), mt (Matches), sm (Similar). Example: https://{cecsdomain}/content/published/api/v1.1/items?q=(name eq "John") Example: https://{cecsdomain}/content/published/api/v1.1/items?q=(type eq "Employee" AND name eq "John") Example: https://{cecsdomain}/content/published/api/v1.1/items?q=(type eq "Employee" AND ((name eq "John" AND field.age ge "40") OR fields.weight gt "70")) Example: https://{cecsdomain}/content/published/api/v1.1/items?q=(taxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489" OR (taxonomies.categories.name co "cat" AND taxonomies.categories.name co "red")) Example: https://{cecsdomain}/content/published/api/v1.1/items?q=(taxonomies.categories.nodes.id eq "9E1A79EE600C4C4BB727FE3E39E95489" OR taxonomies.categories.nodes.name co "cars")
scroll	boolean	Specifying this parameter indicates that the scroll behavior is expected from the Search API. Scrolling is the recommended method for retrieving large result sets. Scrolling is not available when returnMaster is enabled. hasMore will always return false when scrolling is enabled. The offset parameter value, if specified, will be ignored on scroll requests. The limit parameter value will be interpreted in the context of scroll and be fixed for a scroll session. Subsequent changes to limit will be ignored for the scroll session. A limit that results in too large a response will result in a 413 (Payload Too Large) response status. Default Value: false
scrollId	string	This parameter is used to specify the scroll Id. scrollTTL and the original value of the q parameter are always required with requests that use a scrollId to get consistent results. Note that the requirement to always include the q parameter in subsequent scroll requests is currently not validated against previous requests and changes to the parameter within the same scroll session are ignored.
scrollTTL	integer(int32)	scrollTTL (in milliseconds - default and maximum value 30000 ms) specifies the period of inactivity allowed between the current and the next scroll request. All responses to search with scroll include a scrollId. Subsequent scroll requests must include the scrollId returned from the previous response since the scrollId returned could change across requests. Since all scroll requests are stateless, scrollTTL is always expected. The value of scrollTTL does not have to be the same across requests. The original search query (q) is also expected with each subsequent scroll request. An invalid or expired scrollId will result in a 400 (Bad Request) response status. Default Value: 30000
totalResults	boolean	Accepts a boolean value. Setting it to true displays the total results field in the response. The default value is false
twolvl_v1_1	string	This parameter does not need a value and when used it indicates the two level the Search API uses (i) fields.refname.fieldname to search on system fields such as name, description, etc of the referred type; and (ii) fields.refname.fields.userfieldname to search on user-defined fields of the referred type. When this parameter is not used, the two-level search behaves in compatibility mode and only supports searches like fields.reftype.fieldname. Furthermore, when fieldname is the same as a system-defined field name, the two-level search behaves the same as fields.reftype.fields.fieldname.

REST API for Content Management

The following table lists extra search request parameters accepted by the REST API for Content Management:

Query Parameter	Type	Description
channelToken	string	This parameter accepts channelToken of a channel and is used to control the returned results. The result will contain only items targeted to the channel that the specified channelToken belongs to. This can also be achieved by specifying the channels (standard field of an item) contains query condition (channels co "{channelId}") as one of the query conditions in the q query parameter. This is an optional parameter and by default returns all the results.
default	string	Default search query expression which matches the values of the items across all fields.
expand	string	This parameter is used to allow users to get permissions on each matching item. Accepts permissions only.
fields	string	This parameter is used to control the returned fields in each item in the result. This parameter accepts a comma-separated list of field names or all. These fields will be returned for each items in the result. All the field names are case-sensitive, and users must provide the correct field name in the query. All the user-defined field names should be provided with prefix fields and followed by period (.). When fields is specified as all (case-insensitive), all the standard fields are returned in the case of a query across types and in the case of a type-specific query, all standard and user fields are returned. This parameter is optional in the query, and by default the result shows only standard field name and description. The standard fields, Id and type, are always returned irrespective of any field asked. Any incorrect or invalid field name given in the query will throw an error. In the context of a brace style cross-type query, type-specific fields may be specified using the syntax name,{typename1:fields.userdefinedfieldname1,fields.userdefinedfieldname2},{typename2:fields.userdefinedfieldname1}. In the preceding example, all items of the type, typename1, will have fields - name, userdefinedfieldname1, and userdefinedfieldname2, while all items of the type, typename2, will have fields - name, userdefinedfieldname1. If the cross-type query does not resolve to types referenced in the typed fields clause(s), an error will be thrown. Example: This returns standard fields (name), user fields (state), and country of the type address in the search results. https://{cecsdomain}/content/management/api/v1.1/items?q=type eq "Address"&fields=fields.state,fields.country Example: This returns all the attributes for a specific type used in the search results. https://{cecsdomain}/content/management/api/v1.1/items?q=type eq "Address"&fields=all Example: This returns standard fields, name and createdBy in the search results for all items across all the types. https://{cecsdomain}/content/management/api/v1.1/items?fields=name,createdBy Example: This returns all the standard fields in the search results for all items across all the types. https://{cecsdomain}/content/management/api/v1.1/items?fields=all Default value: name, description, repositoryId, slug, language, translatable, createdDate, updatedDate
limit	integer(int32)	This parameter accepts a non negative integer and is used to control the size of the result. If offset+limit > 10000, then the limit is treated as 10000-offset and gives results. The default value is 100.
links	string	This parameter accepts a comma-separated list of link names. By default, this parameter gives all the links applicable. Possible values are: self, canonical, describedby, first, last, prev, next
offset	integer(int32)	This parameter accepts a non negative integer less than 10000 and is used to control the start index of the result. The default value is 0.
orderBy	string	The orderBy parameter is used to control the order (ascending/descending) of queried items. This parameter is optional in the query and by default the results are sorted in the descending order of updatedDate when the default parameter is empty. When the default parameter has value(s), the results are sorted by the relevance of tags of the items to the default values. This parameter accepts featured() or field name separated by a colon (:) for which the user wants to sort the results and sort order. Multiple sort orders are separated by semicolon (;). Format: orderBy={fieldName1}:{asc/desc};{fieldName2}:{asc/desc} Note: asc stands for ascending and desc for descending. asc and desc are always in lower case. In a type-specific query, field names can be either standard fields (name, createdDate, updatedDate) or user-defined fields (single-valued data types (number, decimal, datetime, text). All the user-defined field names should be provided with prefix fields and followed by a period (.). In the context of a cross-type search, this parameter can also have a typed section and takes the form {typename1:fields.userdefinedfieldname1:asc|desc};{typename2:fields.userdefinedfieldname1:asc|desc}. The orderBy parameter only supports one order by field per set of matching braces. While filtering on suggestedTaxonomies, the default sort order will be by relevance of the suggestion to the item. The orderBy parameter also supports the following: Sorting by a two-level field. If there is a two-level sort field, then it can be the only sort field in the orderBy parameter. Sorting assets using user-defined text field or an attribute in JSON data stored in JSON field (embedded content) on assets in a two-level search. Note: The two-level sorting does not work on multiple value fields, so this does not work on multiple text fields. The two-level sorting works on any array attributes on JSON fields because JSON fields can only be a single value field. Sorting by taxonomy root categories and sub-categories of a root category. The additional sorting parameters are as follows: taxonomies.shortName["short name of taxonomy"]:{asc/desc}; taxonomies.categories.nodes.name["short name of taxonomy"|"taxonomy name","category1","category2","category3"] where category1, category2,category3, etc. are sub-categories of a given taxonomy, "taxonomy name". The sort order is optional, and by default it is descending. Any incorrect or invalid field name given in the query will be ignored. When featured() is given and the default parameter has value(s), the results are sorted by the relevance of tags of the items to the default values. Sorting by an attribute in JSON data stored in JSON field on assets. Example: orderBy=name:asc Returns all the items in the ascending order of name. Example: orderBy=updateDate:asc Returns all the items in the ascending order of updateDate. Example: orderBy=fields.age:desc Returns all the items in the descending order of age. Example: orderBy=fields.age Returns all the items in the ascending order of age. Example: default=apples&orderBy=featured() Returns all the items sorted by the relevance of tags of the items to the apples Example: orderBy=fields.blogauthor.authorage Returns all the items in the ascending order of age of the author referred by referenced field, "blogauthor". Example: orderBy=fields.blogauthor.fields.authorage&twolvl_v1_1=true Returns all the items in the ascending order of age of the author referred by the referenced field, "blogauthor". Example: orderBy=taxonomies.shortName["loc"];taxonomies.categories.nodes.name["loc"|"Location","emea","china","industry"];taxonomies.categories.nodes.name["loc"|"Location","americas","brazil","industry"] Returns all the items in the ascending order of the root category of "loc", sub-categories of category whose path is /Location/emea/china/industry, sub-categories of category whose path is /Location/americas/brazil/industry. Example: orderBy=fields.<text_field_name>:asc Returns all the items sorted in the ascending order using the user-defined text field. Example: orderBy=fields.<json_field_name>.value.<attribute_name>:asc Returns all the items sorted in the ascending order using an attribute in JSON data stored in JSON field (embedded content) on assets. Example: orderBy=fields.<ref_field_name><text_field_name>:asc Returns all the items sorted in the ascending order using two-level reference to the user-defined text field. The example uses the compatibility mode of the two-level search. Example: orderBy=fields.<ref_field_name>.fields.<text_field_name>:asc&twolvl_v1_1=true Returns all the items sorted in the ascending order using two-level reference to the user-defined text field. The example uses the two-level mode of the two-level search.
q	string	This parameter accepts a query expression condition that matches the field values. Many such query conditions can be joined using AND/OR operators and grouped with parentheses. The value of the query condition follows the format, {fieldName} {operator} "{fieldValue}". In case of a type-specific query, the field names are limited to standard fields and user-defined fields (except fields of the largeText data type). The only values allowed in the operator are eq (Equals), co (Contains), sw (Startswith), ge (Greater than or equals to), le (Less than or equals to), gt (Greater than), lt (Less than), mt (Matches), sm (Similar). Example: https://{cecsdomain}/content/management/api/v1.1/items?q=(name eq "John") Example: https://{cecsdomain}/content/management/api/v1.1/items?q=(type eq "Employee" AND name eq "John") Example: https://{cecsdomain}/content/management/api/v1.1/items?q=(type eq "Employee" AND ((name eq "John" AND field.age ge "40") OR fields.weight gt "70")) Example: https://{cecsdomain}/content/management/api/v1.1/items?q=(taxonomies.categories.id eq "9E1A79EE600C4C4BB727FE3E39E95489" OR (taxonomies.categories.name co "cat" AND taxonomies.categories.name co "red")) Example: https://{cecsdomain}/content/management/api/v1.1/items?q=(taxonomies.categories.nodes.id eq "9E1A79EE600C4C4BB727FE3E39E95489" OR taxonomies.categories.nodes.name co "cars")
repositoryId	string	This parameter accepts the Id of a repository and is used to control the returned results. The result will contain only items belonging to the specified repository. This can also be achieved by specifying the repositoryId (standard field of an item) equals query condition (repositoryId eq "{repositoryId}") as one of the query conditions in the q query parameter. This is an optional parameter and by default returns results from all the repositories.
scroll	boolean	Specifying this parameter indicates that the scroll behavior is expected from the Search API. Scrolling is the recommended method for retrieving large result sets. Scrolling is not available when returnMaster is enabled. The hasMore parameter will always return false when scrolling is enabled. The offset parameter value, if specified, will be ignored on scroll requests. The limit parameter value will be interpreted in the context of scroll and be fixed for a scroll session. Subsequent changes to limit will be ignored for the scroll session. A limit that results in too large a response will result in a 413 (Payload Too Large) response status. The default value is false.
scrollId	string	This parameter is used to specify the scroll Id. scrollTTL and the original value of the q parameter are always required with requests that use a scrollId to get consistent results. Note that the requirement to always include the q parameter in subsequent scroll requests is currently not validated against previous requests and changes to the parameter within the same scroll session are ignored.
scrollTTL		scrollTTL (in milliseconds - default and maximum value 30000 ms) specifies the period of inactivity allowed between the current and the next scroll request. All responses to search with scroll include a scrollId. Subsequent scroll requests must include the scrollId returned from the previous response since the scrollId returned could change across requests. Since all scroll requests are stateless, scrollTTL is always expected. The value of scrollTTL does not have to be the same across requests. The original search query (q) is also expected with each subsequent scroll request. An invalid or expired scrollId will result in a 400 (Bad Request) response status. The default value is 30000.
totalResults	boolean	This parameter accepts a boolean flag. If specified as true, then the returned result must include the total result count. The default value is false.
twolvl_v1_1	string	This parameter does not need a value. When it is used, it indicates the two levels that the Search API uses (i) fields.refname.fieldname to search on system fields such as name, description, etc of the referred type; and (ii) fields.refname.fields.userfieldname to search on user-defined fields of the referred type. When this parameter is not used, the two-level search behaves in compatibility mode and only supports searches like fields.reftype.fieldname. Furthermore, when fieldname is the same as a system-defined field name, the two-level search behaves the same as fields.reftype.fields.fieldname.

Two-Level Deep Search

By default a search query matches standard or user-defined data fields on the item itself. Data fields on a referenced item may also be searched so long as it is a direct reference. This effectively provides you a way to configure search query that delves two level deep into the data field hierarchy for an item, and therefore, to perform a two-level deep search matching asset standard or user-defined data fields. The two-level search provides the same query expression semantics as those provided while searching the fields of an item. For example:

A search query matching the user-defined field on a reference: /.../api/v1.1/items?q=(type eq "Employee" AND fields.address.street eq "Main St") Here, the address is the name of a reference type field on the type, Employee, which in turn has a field with the name, street.

Note:

Searching recursively down an item's reference hierarchy past the first level reference is not supported. Sorting by second level fields is not supported either.

Two-level deep search supports two ways to configure a search query on standard and user-defined fields on a referenced item:

• Compatibility mode

  This is a default mode. In the compatibility mode, a query expression supports field notations like fields.ref-field.field-name, where ref-field is the name of a reference or a media field and field-name is the name of a field on the referred asset type. Furthermore, when field-name is the same as the name of a standard field (For example, Id, name, or description), the two-level deep search behaves the same as fields.ref-field.fields.field-name, that is, it treats field-name as the name of a user-defined field. For example:

  • Query (type eq "parent-type" AND fields.ref-field.field-name eq "blah") will match items of the type parent-type(parent item) that have the value blah assigned to the user-defined field field-name on the child item, which is set as a reference on the field ref-field.
  • Query (type eq "parent-type" AND fields.ref-field.name eq "blah") will match items of type parent-type (parent item) that have the value blah assigned to the standard field, name on the child item, which is set as reference on the field, ref-field.

• Two-level mode

  This mode is activated by setting the query parameter, twolvl_v1_1 mode to true. In this mode the two-level search query expression uses fields.ref-field.field-name to search on standard fields, such as Id, name, or description and fields.ref-field.fields.field-name to search on user-defined fields of the referenced asset type. For example:

  • Query (type eq "parent-type" AND fields.ref-field.field-name eq "blah") will match items of the type parent-type (parent item) that have the value blah assigned to a standard field, field-name on the child item, which is set as a reference on the field, ref-field.
  • Query (type eq "parent-type" AND fields.ref-field.fields.field-name eq "blah") will match items of the type, parent-type (parent item) that have the value blah assigned to a user-defined field, field-name on the child item, which is set as a reference on the field, ref-field.

Search JSON Data in JSON Fields

Search API allows you to return content items, or digital assets of custom digital asset types, based on search terms matching values assigned to attributes in JSON data that is stored in JSON fields on the item. In the Oracle Content Mangement web interface, the data field for storing JSON formatted data on an asset type is called Embedded Content. The API supports search terms that match base attributes, array elements, or attributes in a JSON object, including an array of objects. JSON data indexing currently imposes the following limitations on the total size of the indexed JSON field (< 2.5MB), JSON field key length (< 512B), and depth to match field in JSON object (10 levels).

Query syntax uses dot notation for field names to reference any key in the arbitrary JSON content, i.e. you can use fields.<json_field_name>.value to query custom text field or you can have fields.<json_field_name>.value.key1.subkey1.subsubkey3, etc. In a search condition, you can use all existing operators that are supported by Search API for regular custom fields, for example:

q=(type eq "Employee" AND fields.<json_field_name>.value.street eq "Main St¿)
q=(type eq "Employee" AND fields.<json_field_name>.value.age gt ¿20")
q=(type eq "Employee" AND fields.<json_field_name>.value.proper`es eq ¿office=HQ¿ AND fields.<json_field_name>.value.proper`es eq ¿building=100¿)

Similarly, for two-level deep search:

q=(type eq "Employee" AND fields.<ref_field_name>.fields.<json_field_name>.value.street eq "Main St¿)
q=(type eq "Employee" AND fields.<ref_field_name>.fields.<json_field_name>.value.age gt ¿20")
q=(type eq "Employee" AND fields.<ref_field_name>.fields.<json_field_name>.value.proper`es eq ¿office=HQ¿ AND fields.<ref_field_name>.fields.<json_field_name>.value.proper`es eq ¿building=100¿)

Use of wildcards in search conditions, such as fields.<json_field_name>.value.*.subsubkey3 and such are not supported for performance reasons.

The Search API also allows you to sort returned search results by JSON Keyes/subkeys, for example:

orderBy= fields.<json_field_name>.value.name:asc
orderBy= fields.<json_field_name>.value.name:desc
orderBy= fields.<ref_field_name>.fields.<json_field_name>.value.name:asc orderBy= fields.<ref_field_name>.fields.<json_field_name>.value.name:desc

Search Across Types

Prior to the 21.6.1 release of Oracle Content Management (June 2021), specifying multiple asset types in a search query made it a global (untyped) query that only allows you to reference standard fields on an asset type in query conditions and in orderBy specifications. An asset type specific predicates like fields.custom-filed-name, which could not be used in the untyped query conditions, fields specification, or orderBy specification. The new cross-type search API and search query syntax associated with it removes these restrictions.

A search query on custom data fields across multiple asset types requires you to use a new syntax for building a search query expression. A query across multiple types is formulated by enclosing asset type predicates with curly brackets {}. The Search query is validated to comply with the following restrictions:

• Only one asset type may be specified within a matching pair of curly brackets. The {} pair defines a type scope.
• Nested asset type scope delimiters are not allowed, for example, {...{...}..} expression would fail validation.
• Curly brackets {} can be combined with square brackets [] when defining a typed expression for the fields or orderBy parameters.
• Predicates specified outside a type scope behave like they were specified using square brackets, that is, like a non-multi-type search query parameter.
• Queries do not support the not equal (ne) operator across different user-defined types.

Examples of search query on custom data fields across multiple asset types:

• {type eq "t1" AND fields.ud1 eq "ud1"}

  ud1 has to be a field on the type, t1. Query will fail validation if that is not the case.

• {type eq "t1" AND fields.ud1 eq "ud1"} AND name eq "John"

  Same as above with a standard field outside the type delimiter.

• {type eq "t1" AND fields.ud1 eq "ud1"} OR {type eq "t2" AND fields.ud2 eq "ud2"}

  ud1 has to be a field on the type, t1 and ud2 has to be a field on the type, t2.

• {type eq "t1" AND and fields.ud1 eq "ud1"} AND {type eq "t2" AND fields.ud2 eq "ud2"}

  Similar to the previous query and valid, but it will return zero results due to the AND operator.

• {type eq "t1" OR type eq "t2"}

  Invalid query, since two types are specified within a type delimiter.

• type eq “t1” OR type eq “t2”

  Un-scoped style search that resolves to an untyped query.

• type eq “t1” OR type eq “t2” AND fields.ud1 eq “ud1”

  Un-scoped style search that resolves to untyped and will throw a validation error.

• type eq “t1” AND fields.ud1 eq “ud1”

  Un-scoped style search that resolves to the type, t1. It is valid as long as ud1 is a field on t1.

• {type eq “t2” AND fields.ud2 eq “ud2”} OR type eq “t1” AND fields.ud1 eq “ud1”

  Un-scoped style search that resolves to the type, t1, and scoped search that resolves to t2. Query is valid if ud1 is a field on t1 and ud2 is a field on t2.

The fields Parameter

The untyped way of configuring the fields parameter on request to return standard and user-defined data fields for a single type uses the form Id, name, type, updatedDate, fields.ud1,fields.ud2. The fields parameter can be typed as well and takes the form {<typename1>:fields.<userdefinedfieldname>,[fields.<userdefinedfieldname>]},{<typename2>:fields.<userdefinedfieldname>,[fields.<userdefinedfieldname>]}.

If an untyped expression is used as the fields parameter value in a combination with a typed query, the q parameter has to resolve to a single un-scoped asset type (a type predicate specified outside {} delimiters), otherwise an exception will be thrown.

Some examples of the typed expression set as the fields parameter value:

• fields=id,name,type,updatedDate,{t1:fields.ud1},{t2:fields.ud2,fields.ud3}

  The typed way to request system-defined fields (Id, name, type, updatedDate) and user defined fields ud1 for type t1 and ud2 and ud3 for type t2. An exception will be thrown during validation if types and user defined fields don’t match.

• fields=id,name,type,updatedDate,{t1:fields.ud1},{t2:fields.ud2},fields.ud3

  The typed way to request system-defined fields (id, name, type, updatedDate) and user defined fields ud1 for type t1 and ud2 for type t2. The user-defined field, ud3, must resolve to an unscoped type, otherwise an exception will be thrown during validation.

The orderBy Parameter

The orderBy parameter can also have a typed section, and it takes the form {<typename1>:fields.<userdefinedfieldname>[:asc|desc]};{<typename2>:fields.<userdefinedfieldname>[:asc|desc]}. The orderBy parameter only supports one order by field per type scope.

Dynamic Count of Assets per Taxonomy Category

The dynamic assets per category category count is a named aggregation, where items matching a search query are further analyzed to answer the question: “How many items in the result set are assigned to a specific category?”. It should be noted that the analyzer needs to reflect direct and indirect category assignments. For example, if an item is assigned to a leaf level category, the item count should propagate to all parent level categories. If the same item is assigned to multiple leaf level categories, it should be counted as one item on the common parent category (and all its parent categories). In other words, duplicate assignments should not be counted. Consider the following example:

Given the following category tree in your taxonomy:	Item count per category should account for a product item D500 assigned to both DSLR and Nikon as follows:
Cameras Type DSLR Brand Nikon	Cameras (1) Type (1) DSLR (1) Brand (1) Nikon (1)

The same result is expected if the item, D500, is also directly assigned to the Cameras category.

If you use taxonomy to allow end-users of a website or application to browse categorized items (for example, in a product catalog on your website), you can use the item count per category to dynamically filter out and hide categories which have no items assigned, while leaving categories that do have assigned items plus, you can display the actual count of assets on each category. Here is how your API client can do that by going through the following repeating cycle to narrow down category listing:

• Start with an initial filter query
• End-user adds a filter term or selects a category
• Run modified filter query plus, an aggregation query(s) as required
• Narrow down the category listing based on the returned aggregated counts
• Cycle repeats from #2 as end-user continues with filtering items

The AGGS Query Parameter

To execute a search query that returns an aggregated item count per category, you need to use the aggs query parameters that takes JSON array as a value. Each element in this array represents an aggregation which is defined by required and optional attributes described in the table below. The /items resource supports the aggs parameter in both the REST API for Content Delivery and REST API for Content Management.

Query Parameter	Type	Aggregation Attributes
aggs	JSON array	name (required): item_count_per_category field (optional): Takes either Id, or apiname to specify if Id or apiName is returned for a category. By default, the category Id is returned. size (optional): Takes a number in the [1...1000] range. By default 1000 is used.

Some examples of search queries with aggregations:

• A query with a single aggregation

  .../api/v1.1/items?fields=name&aggs={"name":"item_count_per_category"}&q=(type eq "ContentType1" AND fields.simple_text_value mt “brown")

• A query with a single aggregation and with the query parameter, limit=0 will return no search results. Aggregated counts will be returned from the Elasticsearch aggregation cache

  .../api/v1.1/items?fields=name&aggs={"name":"item_count_per_category"}&q=(type eq "ContentType1" AND fields.simple_text_value mt “brown")&limit=0

• A query with two aggregations

  .../api/v1.1/items?fields=name&aggs=[{"name":"item_count_per_category"}, {"name":"item_count_per_category","field":"apiname"}]&q=(type eq "ContentType1" AND fields.simple_text_value mt "brown")

The aggregation section in the response to the search request for the above sample query with two aggregations is shown below:

"aggregationResults": [
{
  "itemCountPerCategory": [
    {
      "categoryId": "65EAC164681C47D68851583237381001",
      "itemCount": 3
    },
    {
      "categoryId": "C1E24A8BA3754F5AB17AEED3F020A898",
      "itemCount": 3
    },
    {
      "categoryId": "AF8D57438E3645ABBB137812FE830C34",
      "itemCount": 2
    }
  ],
  "name": "item_count_per_category"
},
{
  "itemCountPerCategory": [
    {
      "categoryApiName": "tax-cat1",
      "itemCount": 3
    },
    {
      "categoryApiName": "tax-cat2",
      "itemCount": 3
    },
    {
      "categoryApiName": "tax-cat3",
      "itemCount": 2
     }
  ],
  "name": "item_count_per_category"
}
]

Aggregation Cache

The aggregated asset count per category API relies on the underlying Elasticsearch requests cache, which is enabled by default on the Oracle Content Management search. By default, the request cache will only cache the results of search requests when the query parameter limit=0, so that it does not cache matching items, but it will cache the hits.total, aggregations and suggestions. This allows frequently used (and potentially heavy) search requests to return results almost instantly. The requests cache keeps the same near real-time promise as uncached search. Elasticsearch invalidates cached results automatically whenever the shard refreshes, but only if the data in the shard has actually changed. In other words, Elasticsearch always get the same results from the cache as it would for an uncached search request.

Using Dynamic Asset Counts per Category API

The dynamic item per category aggregation API can be utilized to display counts as required by the common e-commerce product selectors / product catalogs. This section describes the approach for a typical e-commerce use case as well as more general use cases. The following terms are used to describe the rules for computing the aggregate asset count per category:

• User query: A user-specified search query expression of arbitrary complexity conforming to Oracle Content Management Search API query syntax requirements. This is a free form search query on whatever an end-user entered in the input, such as (name eq "car").
• Category node query: A form of Oracle Content Management Search API query expressed as ‘(taxonomies.categories.nodes.id eq “<id_1>" OR taxonomies.categories.nodes.id eq “<id_2>” OR ... OR taxonomies.categories.nodes.id eq “<id_N>”)’, where id_X is the Id of one of the user-selected categories under a particular taxonomy.
• Search query: One or more search queries intended to fetch results for display to end-users. It can be a user query, one or more category node queries, or a combination of those.
• Aggregation query: A variant of user query, generated to compute the aggregated item count for a specific search facet.

Computing Aggregate Asset Counts

No user-selected categories: With no user-selected categories you can use a user query to get matching items and compute aggregated counts:

• Search query: q=<user_query>
• Aggregation query (all taxonomies): q=<user_query>

User selects one or more categories from one taxonomy - taxonomy-1:

• Search query: q=<user_query> AND <category_node_query_1>
• Aggregation query(taxonomy-1): q=<user_query>
• Aggregation query (all other taxonomies): q=<search_query>

User selects categories from two taxonomy - taxonomy-1 and taxonomy-2:

• Search query: q=<user_query> AND <category_node_query_1> AND <category_node_query_2>
• Aggregation query (taxonomy-1): q=<user_query> AND <category_node_query_2>
• Aggregation query (taxonomy-2): q=<user_query> AND <category_node_query_1>
• Aggregation query (all other taxonomies): q=<search_query>

User selects categories from three taxonomy - taxonomy-1, taxonomy-2 and taxonomy-3:

• Search query: q=<user_query> AND <category_node_query_1> AND <category_node_query_2> AND <category_node_query_3>
• Aggregation query(taxonomy-1): q=<user_query> AND <category_node_query_2> AND <category_node_query_3>
• Aggregation query (taxonomy-2): q=<user_query> AND <category_node_query_1> AND <category_node_query_3>
• Aggregation query (taxonomy-3): q=<user_query> AND <category_node_query_1> AND <category_node_query_2>

A general rule, where user selects categories from N taxonomies:

• Search query: q=<user_query> AND <category_node_query_1> AND <category_node_query_2> ... AND <category_node_query_N>
• Aggregation query (taxonomy-1): q=<user_query> AND <category_node_query_2> ... AND <category_node_query_N>
• Aggregation query (taxonomy-2): q=<user_query> AND <category_node_query_1> AND <category_node_query_3> ... AND <category_node_query_N>
• Aggregation query (taxonomy-N): q=<user_query> AND <category_node_query_1> AND <category_node_query_2> ... AND <category_node_query_N-1>
• Aggregation query (all other taxonomies): q=<search_query>

Total Search Cost

One scored/ranked query to get search results plus aggregate counts for categories under taxonomies with no user-selected categories. N filter queries to compute aggregate counts for N taxonomies with selected categories.

An e-commerce Use Case

The table below lists three taxonomies that are used in this example. It also includes a list of items in repository and item categorization with taxonomies that you can refer to for this example:

Taxonomies	Items and Item Categorization	Item Count per Category
Electronics (ELE) ELE-laptops ELE-keyboards Manufacturer (MAN) MAN-hp MAN-razer Location (LOC) LOC-sheraton-mall LOC-stoneridge-mall	All items below have the same content type ContentType2: HP Elite Dragonfly (added to: ELE-laptops, MAN-hp, LOC-sheraton-mall, LOC-stoneridge-mall) HP Elite Folio (added to: ELE-laptops, MAN-hp, LOC-sheraton-mall, LOC-stoneridge-mall) HP Elite X2 (added to: ELE-laptops, MAN-hp, LOC-sheraton-mall, LOC-stoneridge-mall) HP Pavillion Keyboard (added to: ELE-keyboards, MAN-hp, LOC-sheraton-mall, LOC-stoneridge-mall) HP Omen Keyboard (added to: ELE-keyboards, MAN-hp, LOC-sheraton-mall, LOC-stoneridge-mall) Razer Blade Stealth(added to: ELE-laptops, MAN-razer, LOC-sheraton-mall) Razer Blade Pro(added to: ELE-laptops, MAN-razer, LOC-sheraton-mall) Razer BlackWidow Keyboard (added to: ELE-laptops, MAN-razer, LOC-sheraton-mall) Razer Huntsman Keyboard (added to: ELE-laptops, MAN-razer, LOC-sheraton-mall)	Electronics (ELE) ELE-laptops (5) ELE-keyboards (4) Manufacturer (MAN) MAN-hp (5) MAN-razer (4) Location (LOC) LOC-sheraton-mall (9) LOC-stoneridge-mall (5)

Let's use a simple search query to match all assets for No Categories is Selected to match all assets of the type, Content Type2, in a given repository. To make queries and API response to a search query request easier to read, all categories in the sample taxonomy have the same API name (apiName) as the category name. Therefore, all search query expressions and aggregations below use the apiName. You can use category Id instead.

No Categories is Selected

If end-users didn't select any category yet, you can obtain aggregated asset counts per category using the search query alone.

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2")&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]¿

• Aggregation query (all taxonomies):

  q=<search_query>

Search query response:

{
  "hasMore": false,
  "offset": 0,
  "count": 9
  "limit": 9,
  "items": [
    {
      "name": "HP Omen Keyboard",
      "links": [],
      "id": "COREFE86EA24BAE84D4E87B8A1F992163D6B",
      "type": "ContentType2"
    },
    {
      "name": "Razer BlackWidow Keyboard",
      "links": [],
      "id": "COREF8CEBA1264C04A1A87954C2A4A33D2DB",
      "type": "ContentType2"
    },
    {
      "name": "Razer Huntsman Keyboard",
      "links": [],
      "id": "CORE07C7E1108BFB4A5EAF1761F46251FECD",
      "type": "ContentType2"
    },
    {
      "name": "HP Pavillion Keyboard",
      "links": [],
      "id": "COREAB4987C5FB664007B3B6B4D93CFAC90F",
      "type": "ContentType2"
    },
    {
      "name": "HP Elite X2",
      "links": [],
      "id": "COREF911737800FE406C92183E182C7228CC",
      "type": "ContentType2"
    },
    {
      "name": "HP Elite Folio",
      "links": [],
      "id": "CORE18B3AFABE2814E75AB54CBBF80B3A509",
      "type": "ContentType2"
    },
    {
      "name": "HP Elite Dragonfly",
      "links": [],
      "id": "COREAED2F7C50B404D6FB6547CCE69DD3492",
      "type": "ContentType2"
    },
    {
      "name": "Razer Blade Pro",
      "links": [],
      "id": "CORE66D9CFFF1C2945A7857C6C0B5E4B21BB",
      "type": "ContentType2"
    },
    {
      "name": "Razer Blade Stealth",
      "links": [],
      "id": "CORED009A429B9D04080AE19FF42CE8CC758",
      "type": "ContentType2"  
    }
  ],
  "links": [],
  "aggregationResults": [
    {
      "itemCountPerCategory": [
        {
          "categoryApiName": "loc-sheraton-mall",
          "itemCount": 9
        }, {
          "categoryApiName": "ele-laptops",
          "itemCount": 5 },
        {
          "categoryApiName": "loc-stoneridge-mall",
          "itemCount": 5
        }, {
          "categoryApiName": "man-hp",
          "itemCount": 5 },
        {
          "categoryApiName": "ele-keyboards",
          "itemCount": 4
        }, {
          "categoryApiName": "man-razer",
          "itemCount": 4 }
      ],
      "name": "item_count_per_category"
    }
  ]
}

End-user selected "ELE-laptops"

With one category selected, let's use a search query to get results and obtain aggregated counts for taxonomies with no selected categories. Then we will use a separate aggregate query to compute aggregated counts for the taxonomy, Electronics. The aggregate query can use the parameter limit=0 to return no items, as we are only interested in aggregated counts.

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq “ele-laptops”))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Search query response:

  {
    "hasMore": false,
    "offset": 0,
    "count": 5,
    "limit": 5,
    "items": [
       {
          "name": "HP Elite X2",
          "links": [],
          "id": "COREF911737800FE406C92183E182C7228CC",
          "type": "ContentType2"
       },
       {
          "name": "HP Elite Folio",
          "links": [],
          "id": "CORE18B3AFABE2814E75AB54CBBF80B3A509",
          "type": "ContentType2"
       },
       {
          "name": "HP Elite Dragonfly",
          "links": [],
          "id": "COREAED2F7C50B404D6FB6547CCE69DD3492",
          "type": "ContentType2"
       },
       {
          "name": "Razer Blade Pro",
          "links": [],
          "id": "CORE66D9CFFF1C2945A7857C6C0B5E4B21BB",
          "type": "ContentType2"
       },
       {
          "name": "Razer Blade Stealth",
          "links": [],
          "id": "CORED009A429B9D04080AE19FF42CE8CC758",
          "type": "ContentType2"
       }
     ],
     "links": [],
     "aggregationResults": [
       {
         "itemCountPerCategory": [
           {
             "categoryApiName": "ele-laptops",
             "itemCount": 5
           },
           {
             "categoryApiName": "loc-sheraton-mall",
             "itemCount": 5
           },
           {
             "categoryApiName": "loc-stoneridge-mall",
             "itemCount": 3
           },
           {
             "categoryApiName": "man-hp",
             "itemCount": 3
           },
           {
             "categoryApiName": "man-razer",
             "itemCount": 2
           }
         ],
         "name": "item_count_per_category"
       }
     ]
  }

• Aggregation query (for electronics):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2")&fields=name&limit=0&links=none &aggs[{"name":"item_count_per_category","field":"apiname"}]

  Aggregation query response:

  {
    "hasMore": false,
    "offset": 0,
    "count": 0,
    "limit": 0,
    "items": [],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 9
          },
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 5
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 5
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 5
          },
          {
            "categoryApiName": "ele-keyboards",
            "itemCount": 4
          },
          {
            "categoryApiName": "man-razer",
            "itemCount": 4
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

End-user selected "ELE-laptops" plus "MAN-hp"

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "ele-laptops") AND (taxonomies.categories.nodes.apiName eq "man-hp"))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Search query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 3,
    "limit": 3,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 3
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

• Aggregation query (for electronics):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "man-hp"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Aggregation query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 5,
    "limit": 5,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      },
      {
        "name": "HP Pavillion Keyboard",
        "links": [],
        "id": "COREF0AED9516AED4DC6A0692A696170FD57",
        "type": "ContentType2"
      },
      {
        "name": "HP Omen Keyboard",
        "links": [],
        "id": "CORE816259C0386D4704AB006B9F40D9F457",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 5
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 5
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 5
          },
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 3
          },
          {
            "categoryApiName": "ele-keyboards",
            "itemCount": 2
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

• Aggregation query (for manufacturer):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "ele-laptops"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Aggregation query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 5,
    "limit": 5,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      },
      {
        "name": "Razer Blade Stealth",
        "links": [],
        "id": "COREF49CB87945574CC59B2ACAE38A46D529",
        "type": "ContentType2"
      },
      {
        "name": "Razer Blade Pro",
        "links": [],
        "id": "CORE51A676D1B2FF4DB5B975806AFAF69284",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 5
          },
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 5
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 3
          },
          {
            "categoryApiName": "man-razer",
            "itemCount": 2
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

End-user selected "ELE-laptops" plus "MAN-hp" and "LOC-stonebrifge-mall"

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "ele-laptops") AND (taxonomies.categories.nodes.apiName eq "man-hp") AND (taxonomies.categories.nodes.apiName eq "loc-stoneridge-mall"))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Search query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 3,
    "limit": 3,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 3
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

• Aggregation query (for electronics):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "man-hp") AND (taxonomies.categories.nodes.apiName eq "loc-stoneridge-mall"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Aggregation query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 5,
    "limit": 5,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      },
      {
        "name": "HP Pavillion Keyboard",
        "links": [],
        "id": "COREF0AED9516AED4DC6A0692A696170FD57",
        "type": "ContentType2"
      },
      {
        "name": "HP Omen Keyboard",
        "links": [],
        "id": "CORE816259C0386D4704AB006B9F40D9F457",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 5
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 5
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 5
          },
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 3
          },
          {
            "categoryApiName": "ele-keyboards",
            "itemCount": 2
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

• Aggregation query (for manufacturer):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "ele-laptops") AND (taxonomies.categories.nodes.apiName eq "loc-stoneridge-mall"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Aggregation query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 3,
    "limit": 3,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 3
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

• Aggregation query (for location):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType2" AND (taxonomies.categories.nodes.apiName eq "ele-laptops") AND (taxonomies.categories.nodes.apiName eq "man-hp"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

  Aggregation query response

  {
    "hasMore": false,
    "offset": 0,
    "count": 3,
    "limit": 3,
    "items": [
      {
        "name": "HP Elite Dragonfly",
        "links": [],
        "id": "CORE02B5199C0C154F9AB29C42F829A47F21",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite Folio",
        "links": [],
        "id": "COREAAC11256104F4D73AAF599230621A789",
        "type": "ContentType2"
      },
      {
        "name": "HP Elite X2",
        "links": [],
        "id": "COREDCF70DB8B3CA4479876D759A3B7A39AC",
        "type": "ContentType2"
      }
    ],
    "links": [],
    "aggregationResults": [
      {
        "itemCountPerCategory": [
          {
            "categoryApiName": "ele-laptops",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-sheraton-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "loc-stoneridge-mall",
            "itemCount": 3
          },
          {
            "categoryApiName": "man-hp",
            "itemCount": 3
          }
        ],
        "name": "item_count_per_category"
      }
    ]
  }

A General Use Case

The table below includes the three taxonomies that are used in the example. It also includes a list of items in the repository and the item categorization with taxonomies that you can refer to:

Taxonomies	Items and Item Categorization	Item Count per Category
TA1 TA1-cat_0 TA1-cat_0_1 TA1-cat_0_1_1 TA1-cat_0_1_1_1 TA1-cat_0_2 TA1-cat_0_2_1 TA1-cat_0_2_1_1 TA2 TA2-cat_0 TA2-cat_0_1 TA2-cat_0_1_1 TA2-cat_0_1_1_1 TA3 TA3-cat_0 TA3-cat_0_1 TA3-cat_0_1_1 TA3-cat_0_1_1_1	All items below have the same content type, ContentType1: Item1 (added to: TA1-cat_0_1_1_1) Item2 (added to: TA1-cat_0_1_1, TA1-cat_0_2_1, TA2-cat_0_1_1, TA3-cat_0_1_1) Item3 (added to: TA3-cat_0_1_1_1) Item4 (added to: TA2-cat_0_1, TA3-cat_0_1) Item5 (added to: TA3-cat_0_1)	TA1 TA1-cat_0 (2) TA1-cat_0_1 (2) TA1-cat_0_1_1 (2) TA1-cat_0_1_1_1 (1) TA1-cat_0_2 (1) TA1-cat_0_2_1 (1) TA1-cat_0_2_1_1 (0) TA2 TA2-cat_0 (2) TA2-cat_0_1 (2) TA2-cat_0_1_1 (1) TA2-cat_0_1_1_1 (0) TA3 TA3-cat_0 (4) TA3-cat_0_1 (4) TA3-cat_0_1_1 (2) TA3-cat_0_1_1_1 (1)

Just like in the e-commerce use case, we will use a simple search query to match all assets for No Categories is Selected to match all assets of the type, Content Type1 in a given repository. To make queries and API response to a search query request easier to read, all categories in the sample taxonomy have the same API name (apiName) as the category name. Therefore, all search query expressions and aggregations below use the apiName. You can use the category Id instead.

No Categories is Selected

With no end-user selection made, we can obtain aggregate asset counts per category using a search query alone.

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq “ContentType1”)&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}

• Aggergate query:

  q=<search_query>

End-user delected TA1-cat_0_1_1 plus TA1-cat_0_2_1

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta1-cat_0_1_1" OR taxonomies.categories.nodes.apiName eq “ta1-cat_0_2_1"))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA1):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1"&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}

• Aggregation query (taxonomies with no category selected):

  q=<search_query>

End-user selected TA2-cat_0_1_1

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta2-cat_0_1_1"))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA2):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1"&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}

• Aggregation query (taxonomies with no category selected):

  q=<search_query>

End-user selected TA3-cat_0_1_1

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta3-cat_0_1_1"))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA3):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1"&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}

• Aggregation query (taxonomies with no category selected):

  q=<search_query>

End-user selected TA1-cat_0_1_1, TA1-cat_0_2_1 plus TA2-cat_0_1_1

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta1-cat_0_1_1" OR taxonomies.categories.nodes.apiName eq "ta1-cat_0_2_1") AND (taxonomies.categories.nodes.apiName eq “ta2-cat_0_1_1”))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA1):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND(taxonomies.categories.nodes.apiName eq "ta2-cat_0_1_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA2):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND(taxonomies.categories.nodes.apiName eq "ta1-cat_0_1_1" OR taxonomies.categories.nodes.apiName eq "ta1-cat_0_2_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (taxonomies with no category selected):

  q=<search_query>

End-user selected TA2-cat_0_1 plus TA3-cat_0_1

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta2-cat_0_1") AND (taxonomies.categories.nodes.apiName eq “ta3-cat_0_1”))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA2):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta3-cat_0_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (for TA3):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta2-cat_0_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (taxonomies with no selected categories):

  q=<search_query>

End-user selected TA1-cat_0_1_1, TA1-cat_0_2_1, TA2-cat_0_1_1 plus TA3-cat_0_1_1

• Search query:

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta1-cat_0_1_1" OR taxonomies.categories.nodes.apiName eq "ta1-cat_0_2_1") AND (taxonomies.categories.nodes.apiName eq "ta2-cat_0_1_1") AND (taxonomies.categories.nodes.apiName eq “ta3-cat_0_1_1”))&fields=name&links=none&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query(for TA1):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta2-cat_0_1_1") AND (taxonomies.categories.nodes.apiName eq "ta3-cat_0_1_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query(for TA2):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta1-cat_0_1_1" OR taxonomies.categories.nodes.apiName eq "ta1-cat_0_2_1") AND (taxonomies.categories.nodes.apiName eq "ta3-cat_0_1_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query(for TA3):

  q=(repositoryId eq "<repo_ID>" AND type eq "ContentType1" AND (taxonomies.categories.nodes.apiName eq "ta1-cat_0_1_1" OR taxonomies.categories.nodes.apiName eq "ta1-cat_0_2_1") AND (taxonomies.categories.nodes.apiName eq "ta2-cat_0_1_1"))&fields=name&links=none&limit=0&aggs=[{"name":"item_count_per_category","field":"apiname"}]

• Aggregation query (taxonomies with no selected categories):

  q=<search_query>

Scroll API

Scrolling or a scroll request is the recommended way of retrieving enormous search result sets. It is invoked by adding the boolean parameter, scroll=true, to a search request. The result of the first scroll search request, if successful, returns a scrollId in the response. All subsequent scroll requests of a first scroll request must supply the returned scrollId as a parameter, scrollId=<scrollId value>. The scrollId may change across subsequent scroll requests, so clients should always send the scrollId returned by the previous scroll response in a session. The q parameter specified with the first scroll request must also be specified with each subsequent scroll request. All results matched by a scroll search will have been retrieved when a scroll request returns 0 results or no scrollId is set on the response.

The number of results returned per page of a scroll search request is determined by the limit parameter. The limit parameter specified for the first scroll request will stay in effect for the life of the scroll session. As in other cases, a limit value that results in too large of a search response will result in a HTTP status code 413.

Scrolling is an expensive operation for the search server, so scroll sessions are aggressively cleaned up. If more than scrollTTL milliseconds elapse between subsequent scroll requests, the scroll session is cleaned up and any further usage of the session scrollId will result in an error. The maximum (and default) value for scrollTTL is 30000 ms (30s). It is recommended to have shorter scrollTTL values if feasible.

Note:

The hasMore parameter will always return false for scroll searches. Scroll cannot be used when the returnMaster parameter is set to true.

Example of a Scroll API Session

First scroll request: /api/v1.1/items?q=(type eq "Employee" AND fields.role eq "Senior Developer")&scroll=true&scrollTTL=5000

• Truncated first scroll response with scrollId: scrollId=abcdefghij

Subsequent scroll request: /api/v1.1/items?q=(type eq "Employee" AND fields.role eq "Senior Developer")&scrollId=abcdefghij&scrollTTL=3000 (note scrollTTL can change)

• Truncated subsequent scroll response with scrollId: scrollId=pqrstuvw

Subsequent scroll request: /api/v1.1/items?q=(type eq "Employee" AND fields.role eq "Senior Developer")&scrollId=pqrstuvw&scrollTTL=3000

• Truncated final scroll response: count=0

Custom Ranking Policies

The REST API for Content Delivery, by default, applies a built-in ranking policy described below to calculate the relevance score for items matching a search query. Oracle Content Management allows you to override a built-in policy and control the relevance score of items matching a search query in the REST API for Content Delivery by defining a custom ranking policy, which contains a collection of ranking methods with configurable properties that relate to:

• Searchable standard and custom fields on content items or attributes on digital assets
• Indexed items to ranking method matching condition
• Impact on the item relevance score impact: Score increase or decay.
• Decay function

The search in the REST API for Content Management, by default, applies a built-in ranking policy to calculate the relevance score for items matching a search query. The use of custom ranking policies in the management search is not supported.

The search in the REST API for Content Delivery allows you to use a custom ranking policy as:

• Global Default: A ranking policy set as the global default overrides a built-in ranking policy and is applied by default to calculate the relevance score for items matching a search query.
• Channel Default : A ranking policy set as the channel default overrides a built-in ranking policy or the global default and is applied by default to calculate the relevance score for items matching a search query for this channel.
• rankBy parameter value: A ranking policy set as the value of the rankBy parameter on a search query request overrides any default policy and is applied to calculate the relevance score for items returned in the response.

Built-in Ranking Policy

The built-in ranking policy uses the following similarity ranking to calculate the relevance score for matched items:

• Elasticsearch Relevance Score: By default items matching a search query are ranked by the Elasticsearch similarity relevance score (the Okapi BM25 algorithm).
• Term Frequency in a Multi-Term Query: For a multi-term search query, the Elasticsearch relevance score algorithm will take into account the term frequency (tf) when calculating the score for items matching either type-specific searches, or default (no type specified) searches.
• Stemmed Matches: The scoring algorithm will apply the same rank to non-stemmed and stemmed matches (for example, OCI compute topology and OCI compute topologies are equivalent). Within the group of matches with the same stem, the rank of non-stemmed matches is higher than the rank of stemmed matches.

Custom Ranking Policies

Custom ranking policies in Oracle Content Management allow you to change relevance scores of items matching a search query using the settings specified in the policy, independently from the structure of the submitted search query. That is achieved by giving you ability to define methods on a ranking policy to control:

• Matching Rule: What standard or user-defined fields on an asset type require matching (exact term - EQ or phrase match - MT) to given values for the ranking method to apply.
• Score Change: The impact a matching data field will have on the relevance score of an item (boost its original score or decrease it over time).

The two types of ranking methods available are boost and pin methods. These methods allow you to increase an item's relevance score, while decay methods decrease the score over a period of time.

To understand how ranking policy works, consider a simple example which uses items of the content type, automotive:

• Item 1: (name: Ferrari, description: Ferrari)
• Item 2: (name: Bugatti, description: Bugatti)

The following search queries will match and return both items, but the relevance scores calculated by the built-in ranking policy will be different. Thus, items will be returned in a different order with neither item potentially returned at the top by query 2.

• Query 1: q=type eq “Automotive” and (description eq “Ferrari” or name eq “Bugatti”)
• Query 2: q=type eq “Automotive”

If you want search queries to always return items about Bugatti cars at the top (pinned) and items about Ferrari cars among the top matching items, you can define a custom ranking policy with two rules: boost - description (weight: 10, value: Ferrari) and pin - name (value: Bugatti). If this policy is used, either query will consistently return item 2 at the top and boost the relevance score of item 1 from the structure of the query:

• Query 1 result: Item 1 (Ferrari) boosted to 10 and Item 2 (Bugatti) is pinned
• Query 2 result: Item 1 (Ferrari) boosted to 10 and Item 2 (Bugatti) is pinned

Custom Ranking Policies Lifecycle

A new ranking policy is created as a draft version, which you can promote. Promoting a draft version of a ranking policy creates a promoted version. Users with the Content Administrator role can set a promoted ranking policy as the global default. A manager on a publishing channel can assign the promoted version as a channel default policy to it. Just as the localization policy, only one ranking policy can be assigned to a channel at a time.

To make a ranking policy available in the REST API for Content Delivery, it needs to be published to create a published version. Content administrators can publish a ranking policy on the ranking policies page.

The following table summarizes actions that are allowed on a ranking policy and the policy status in Content Preview or Delivery Search API depending on the available versions of the policy:

Available Version	Promote	Set as Channel Default	Set as Global Default	Publish	Unpublish	Delivery API
Draft	yes	no	no	no	n/a	no
Promoted	n/a	yes	yes	yes	n/a	no
Published	n/a	yes	yes	n/a	yes	active

Note:

• Draft, promoted, and published versions have the same policy descriptor which uniquely identifies a ranking policy.
• The active status means that results matching a search query in the REST API for Content Delivery will be ranked by relevance based on the rules defined in the ranking policy if it is set as a global default, assigned as a channel default, or specified in the rankBy parameter on the request URL.

Supported Ranking Methods

A custom ranking policy in Oracle Content Managementis a collection of ranking methods, each defined to match a standard or user-defined data field on asset types and then boost or decrease the relevance score of matching items. When a ranking policy is applied, an item matching a search query that you submitted can meet matching rules in one method, several methods, or none. If the item didn't match any method, its relevance score remains the same as calculated by the built-in ranking policy (Elasticsearch), original score. If an item matches one method, its original score is multiplied by the parameter weight value set on this method. If the item matches more than one ranking method, its relevance score = original score * weight1 * weight2 * ...

The following ranking methods are currently supported in Oracle Content Management for defining custom ranking policies:

Ranking Method	Method Parameters	Data Field Type Compatibility	Comment
Boost - Equals	asset type - field {1-n} value {1-m} weight	Text, Date, Numeric	If more than one value is set for a selected data field, OR is used in the expression to match items for boosting. The value of the date type is matched within a given time interval.
Boost - Phrase Match	asset type - field {1-n} value {1-m} weight	Text	If more than one value is set for a selected data field, OR is used in the expression to match items for boosting. A phrase value is matched anywhere in the field data. For example, if the value set on the method is Italy, it will match both "Italy is a European country" or "Rome is the capital of Italy" phrases.
Pin - Equals	asset type - field {1-n} value {1-m}	Text, Date, Numeric	Weight is a server-controlled value that is large enough to ensure pinned items bubble up on the top. If more than one value is set for a selected field, OR is used in the expression to match items for pinning.
Pin - Phrase Match	asset type - field {1-n} value {1-m}	Text	Weight is a server-controlled value that is large enough to ensure pinned items bubble up on the top. If more than one value is set for a selected field, OR is used in the expression to match items for pinning.
Decay - Date	asset type - field {1-n} origin offset scale	Date	Standard fields: Only publishedDate field or user-defined fields: Any field of the date type. Method decreases the existing relevance score of an item.
Decay - Numeric	asset type - field (1-n} origin offset scale	Numeric	User-defined fields: Any field of the numeric type. Method decreases existing relevance score of an item.

Note:

• In Typed searches, that is, for search requests that explicitly specify asset types in the search query expression, Boost, Pin or Decay ranking methods will use both standard and user-defined data fields on asset types to match items for boosting, pinning, or decreasing their relevance score.
• In Untyped or Default searches, that is, for search requests that do not specify asset types in the search query expression, Boost, Pin or Decay ranking methods will use only standard data fields on asset types to match items for boosting, pinning, or decreasing their relevance score.
• Multiple matching fields : If a ranking method is configured to match several fields on an asset type, then the relevance score of the items that match several or all fields will be a multiple of weights set on the method. For example, if two fields in ranking method with weight 20 are matched, then the item score will be 20 x 20 = 400.

The Boost - Equals Method

The Boost - Equals method allows you to increase the relevance score of an item that matches the submitted search request so long as the item has the asset types set in the method and its fields match the exact value set in the method ( the EQ operator is applied for matching the field value). The original relevance score of an item is multiplied by the weight defined in the method.

If the item matches more than one field defined on the Boost - Equals or Boost - Phrase Match method, its relevance score is calculated as follows:

• Item matches single field: Item score = original score * weight
• Item matches several fields: Item score = original score * weight * weight * ...

Note:

The field value of the date type on an asset matches the value set in the Boost - Equals method within time interval from Value to Value + Offset.

Sample request

PUT /content/management/api/v1.1/search/rankingPolicies/5A487437500042849B54FE3BA4EC80C2?q=(status%20eq%20%22draft%22)&fields=all
 
{
  "name": "rp1",
  "description": "",
  "apiName": "rp1",
  "entries": [
    {
      "key": {
        "name": "myBoostEquals",
        "methodType": "equal",
        "weight": 10,
        "values": [
          {
            "type": "text",
            "entries": [
              "cat"
            ]
          },
          {
            "type": "numeric",
            "entries": []
          },
          {
            "type": "datetime",
            "entries": [
              {
                "origin": "2022-05-10T00:00:00.000-07:00",
                "originTimeZone": "America/Los_Angeles",
                "offset": "10d"
              }
            ]
          }
        ],
        "type": "boostMethod"
      },
      "value": [
        {
          "name": "name",
          "contentType": "myType1",
          "weightMultiplier": 2,
          "type": "standardAssetField"
        },
        {
          "name": "published date",
          "contentType": "myType1",
          "weightMultiplier": 1,
          "type": "standardAssetField"
        }
      ]
    }
  ],
  "policyId": "B025517B9D47454A9311EDD3D4D92BD6"
}

The Boost - Phrase Match Method

The Boost - Phrase Match method allows you to increase the relevance score of an item that matches the submitted search request so long as the item has the asset types set in the method and its fields match the phrase value set in the method (the MT operator is applied for matching the field value). The original relevance score of the item is multiplied by the weight defined in the method.

Sample request

PUT /content/management/api/v1.1/search/rankingPolicies/5A487437500042849B54FE3BA4EC80C2?q=(status%20eq%20%22draft%22)&fields=all
 
{
  "name": "rp1",
  "description": "",
  "apiName": "rp1",
  "entries": [
    {
      "key": {
        "name": "myBoostMethod1",
        "methodType": "phraseMatch",
        "weight": 10,
        "values": [
          {
            "type": "text",
            "entries": [
              "cat"
            ]
          }
        ],
        "type": "boostMethod"
      },
      "value": [
        {
          "name": "name",
          "contentType": "myType1",
          "weightMultiplier": 2,
          "type": "standardAssetField"
        },
        {
          "weightMultiplier": 10,
          "contentType": "myType1",
          "name": "myField1",
          "type": "customAssetField",
          "id": "2332EA112CD140F7A4D6847451B1355F"
        }
      ]
    }
  ],
  "policyId": "B025517B9D47454A9311EDD3D4D92BD6"
}

The Pin - Equals Method

The Pin - Equals method allows you to set the topmost relevance to an item that matches the submitted search request so long as the item has the asset types set in the method and its fields match the exact value set in the method (the EQ operator is applied for matching the field value).

If the item matches more than one field defined on the Pin - Equals or Pin - Phrase Match method, its relevance score is calculated as follows:

• Item matches single field: Item score = original score * 5000
• Item matches several fields: Item score = original score * 5000 * 5000 * ...

Note:

The field value of the date type on an asset is matched to the value set in the Pin - Equals method within the time interval from Value to Value + Offset.

Sample request

PUT /content/management/api/v1.1/search/rankingPolicies/5A487437500042849B54FE3BA4EC80C2?q=(status%20eq%20%22draft%22)&fields=all
 
{
  "name": "rp1",
  "description": "",
  "apiName": "rp1",
  "entries": [
    {
      "key": {
        "values": [
          {
            "type": "text"
          },
          {
            "type": "numeric"
          },
          {
            "type": "datetime",
            "entries": [
              {
                "origin": "2022-05-10T00:00:00.000-07:00",
                "originTimeZone": "America/Los_Angeles",
                "offset": "12h"
              }
            ]
          }
        ],
        "name": "myPinEquals1",
        "type": "pinMethod",
        "methodType": "equal"
      },
      "value": [
        {
          "contentType": "myType1",
          "name": "name",
          "type": "standardAssetField"
        },
        {
          "contentType": "myType1",
          "name": "published date",
          "type": "standardAssetField"
        }
      ]
    }
  ],
  "policyId": "B025517B9D47454A9311EDD3D4D92BD6"
}

The Pin - Phrase Match Method

The Pin - Phrase Match method allows you to set the topmost relevance to the item that matches the submitted search request so long as the item has the asset types set in the method and its fields match the phrase value set in the method (the MT operator is applied for matching the field value).

Sample request

PUT /content/management/api/v1.1/search/rankingPolicies/5A487437500042849B54FE3BA4EC80C2?q=(status%20eq%20%22draft%22)&fields=all
 
{
  "name": "rp1",
  "description": "",
  "apiName": "rp1",
  "entries": [
    {
      "key": {
        "values": [
          {
            "type": "text",
            "entries": [
              "cat",
              "black"
            ]
          }
        ],
        "name": "myPinPhraseMatch1",
        "type": "pinMethod",
        "methodType": "phraseMatch"
      },
      "value": [
        {
          "contentType": "myType1",
          "name": "description",
          "type": "standardAssetField"
        },
        {
          "contentType": "myType1",
          "name": "name",
          "type": "standardAssetField"
        },
        {
          "contentType": "myType1",
          "name": "myfield1",
          "type": "customAssetField",
          "id": "8921A6FDFD1C4C2AB966DE0BA1FDFF3D"
        }
      ]
    }
  ],
  "policyId": "B025517B9D47454A9311EDD3D4D92BD6"
}

The Decay - Date Method

The Decay - Date method allows you to decrease the relevance of an item that matches the submitted search request so long as the item has the asset types set in the method. The relevance score that this item has at the origin date will decrease the further value of the date field selected on the asset type gets away from the origin.

Currently the Decay - Date or Decay - Numeric method in Oracle Content Management does not support Gaussian, exponential, or linear decay functions that are supported in Elasticsearch. Instead Oracle Content Management allows you to define a step-down decay function to achieve a similar effect:

The calculated relevance score of an item with the field value matching origin +/- offset is multiplied by the weight which is calculated by the Decay method. The relevance score of the matching item may be boosted by a Boost ranking method. If scale = 0, the weight drops to 0 whenever the field value is above origin + offset or below origin - offset values. Otherwise, the weight drops to half of the decay value for the duration of the scale value and then drops to 0.

Sample request

PUT /content/management/api/v1.1/search/rankingPolicies/5A487437500042849B54FE3BA4EC80C2?q=(status%20eq%20%22draft%22)&fields=all
 
{
  "name": "rp1",
  "description": "",
  "apiName": "rp1",
  "entries": [
    {
      "key": {
        "name": "myDecayDate",
        "type": "decayMethod",
        "origin": "2022-05-10T00:00:00.000-07:00",
        "originTimeZone": "America/Los_Angeles",
        "offset": "6h",
        "scale": "12h",
        "decay": "0.1",
        "methodType": "date"
      },
      "value": [
        {
          "contentType": "myType1",
          "name": "published date",
          "type": "standardAssetField"
        }
      ]
    }
  ],
  "policyId": "B025517B9D47454A9311EDD3D4D92BD6"
}

The Decay - Numeric Method

The Decay - Numeric method allows you to decrease the relevance of the item that matches the submitted search request so long as this item has the asset type set in the method. The relevance score that this item has initially will decrease the further value of the numeric field selected on the asset type gets away from the origin value.

The Decay - Numeric method uses the same step-down decay function as the Decay - Date method.

Sample request

PUT /content/management/api/v1.1/search/rankingPolicies/5A487437500042849B54FE3BA4EC80C2?q=(status%20eq%20%22draft%22)&fields=all
 
{
  "name": "rp1",
  "description": "",
  "apiName": "rp1",
  "entries": [
    {
      "key": {
        "name": "myDecayNumeric",
        "type": "decayMethod",
        "origin": "10",
        "offset": "2",
        "scale": "5",
        "decay": "0.1",
        "methodType": "numeric"
      },
      "value": [
        {
          "contentType": "myType1",
          "name": "mynumberfield1",
          "type": "customAssetField",
          "id": "F0C4FA257D5B4C6C81656837D867B29E"
        }
      ]
    }
  ],
  "policyId": "B025517B9D47454A9311EDD3D4D92BD6"
}