Content Properties in the REST API
What are content properties?
Content properties are a key-value storage associated with a piece of Confluence content, and are one of the forms of persistence available to you as an add-on developer. Content properties free you from having to use your own data store, by allowing you to store up to 32KB of JSON with each piece of content (a page, blog post, or an attachment). If you need to store metadata about a piece (or pieces) of content, for example, this is a great way to do it.
Content properties are accessible both by Java and REST APIs.
Query content properties with CQL
You can now use CQL to query content properties in your Confluence instance. For example, a plugin could store the number of likes on a page in a content property, then by creating an index schema module for that property you can query the values to see how many pieces of content have more than 20 likes. See the section on the CQL Search Extension for more information.
GET, POST, and DELETE content properties
To retrieve any existing content properties for a piece of content, perform a GET on the endpoint
To add content properties to a piece of Confluence content, perform a POST to the same endpoint. The key in your content property can be an arbitrary string (like "myprop"), whereas the value must be structured JSON.
If you need to delete content properties, you can perform a DELETE on the endpoint
Fetch content properties as an expansion when retrieving content
Content properties are now available as an expansion on the content resource. This allows content properties to be retrieved in the same REST call as fetching the content itself. This expansion is available from any resource that returns content, including the CQL search resource.
CQL search extension
To allow searching of content properties using CQL, you can enable indexing of data stored as content properties by defining an index schema. You can define an exclusive index schema for each content property key; then, whenever a content property is saved, Confluence checks if a schema was defined for its key. If a schema exists, indexable values are extracted from content property values and stored in an index. There can only be one index schema definition for a content property key, so any duplicates will be disabled. In the case of offending keys, an appropriate log message will be available.
Index schema definition
When defining an index schema for content properties, you need to provide a set of extraction expressions and field type pairs, which are used to retrieve a specific value from a JSON document and transform it into the desired representation. Supported index field types are:
See the below JSON document and its index schema as an example:
|Extraction definition for a P2 plugin||Extracted value|
||1st of Jan 2000 00:00:00.000 UTC|
||An array containing
Use dot-notation to access an embedded field in a document (as shown below). After successful validation, all extracted values are stored inside an index and you can address them in CQL queries.
Putting it all together, here's a sample index schema definition:
Note : Index schemas for connect have not been released in 5.7-OD-42
Field type doesn't only specify how data is stored in the index, but also determines which CQL operators are available in your query.
Supported index field types
|Type||Description||Supported CQL operators|
||Entire extracted value will be indexed as a single token, without any filtering. When extraction expression evaluates to a JSON array, each element will be indexed separately. Enables searching for an exact value, e.g. unique identifier.||
||Extracted value will be tokenized before indexing, allowing searching for a particular words.||
||Extracted number will be indexed as a
||Two representation are possible, either a
Querying with CQL
Indexed content properties can be addressed in a CQL query using the
content.property field handler. Any content that contains content properties matching the query are returned in the results.
The query syntax is as follows:
content.property[<KEY>].<PATH> <OPERATOR> value
Note the dot notation when referencing embedded fields like 'content.likes'
|KEY||The key of the content properties you're searching.|
|PATH||The path to the value you'd like to search in the JSON document (use dot notation for embedded fields).|
|OPERATOR||One of the supported CQL operators for the field type.|