When working with Alfresco, developers often query content using either CMIS (Content Management Interoperability Services) or FTS (Full Text Search). But there's a small gotcha that often trips people up: special characters like hyphens (`-`) behave differently depending on the query language.
If you've ever seen something like _x002d_ in a query and wondered what it means (or why your CMIS query fails when FTS works perfectly) this post is for you.
TL;DR
- CMIS requires escaping special characters (e.g.,
- becomes _x002d_)
- FTS does not require escaping, so
- works as-is
- If your query breaks in CMIS but works in FTS, check your identifiers for special characters
Background: Custom Content Model Example
Let’s say you’ve created a custom aspect called test:test-1. Here’s a sample content model snippet
<aspect name="test:test-1">
<properties>
<property name="test:flag">
<type>d:boolean</type>
</property>
</properties>
</aspect>
This aspect might be used in your repository to tag documents with a boolean test:flag
Querying with Alfresco FTS
FTS is flexible with special characters. You can run a query like this with no issues
ASPECT:"test:test-1"
Or combine it with other conditions
ASPECT:"test:test-1" AND test:flag:true
It Just Works™.
Querying with CMIS: Escaping Required
However, try something similar with CMIS and you'll get errors if you don’t escape the hyphen:
❌ Invalid CMIS query
SELECT * FROM cmis:document WHERE test:test-1 IS NOT NULL
✅ Correct CMIS query
SELECT * FROM cmis:document WHERE test:test_x002d_1 IS NOT NULL
Likewise, for properties
SELECT * FROM cmis:document WHERE test:flag = true AND test:test_x002d_1 IS NOT NULL
Here, - is escaped as _x002d_, which is the Unicode escape sequence for the hyphen
Final Thoughts
If you’re dynamically generating CMIS queries, make sure to escape special characters in qualified names (QName). This is particularly important for custom types and aspects with hyphens or other reserved characters.
FTS is more forgiving, but if you're using CMIS (especially in integrations or reporting tools), escaping is not optional.
Still confused? Drop a comment or raise an issue!
