aem-querybuilder v1.0.2

About

This is a small utility that produce necessary parameters to AEM's query builder servlet.

Requirements

This library can be used both in browsers and server-side applications.

Include polyfill for Object.assign, Object.fromEntries and Array.prototype.flatMap in legacy environments.

This utility is written in CommonJS module. For ES Module or UMD environment, or either class, generator, destructuring assignment, rest parameter, spread operator or optional chaining operator is not supported, please transcompile using tools like webpack or babel.

TypeScript support

When using in TypeScript projects with tsc, set the following flags to true in tsconfig.json:

{
    "compilerOptions": {
        "skipLibCheck": true,
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true
    }
}

which can then be imported as follow:

import QueryBuilder from 'aem-querybuilder';

Examples

const QueryBuilder = require('aem-querybuilder');
const query = new QueryBuilder({
    type: 'cq:Page',  // find all pages
    path: '/content', // under /content
    where: {          // where title contains Sample
        'jcr:content/jcr:title': { like: 'Sample' }
    },
    select: '*',      // select all properties
    nodeDepth: 1,     // including direct children's
    limit: 10         // limiting to 10 results
});

// using GET
fetch('http://localhost:4502/bin/querybuilder.json?' + query);

// using POST
fetch('http://localhost:4502/bin/querybuilder.json', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: query.toString()
});

// getting the list of parameters for further processing
const params = query.toJSON();

Reference

Documentation here is meant to demostrate how to generate the query parameters. For reference on AEM's query builder API itself, please refer to official documentation.

Predicate interface

One or more predicates are specified through the Predicate interface. It is essentially an object with known property keys.

Multiple predicates on a single Predicate object are always joined by and:

{
    path: P1,
    nodename: P2,
    where: {
        property1: P3,
        property2: P4
    }
}

are translated as

(path: P1) and (nodename: P2) and (property1: P3) and (property2: P4)

P3 and P4 in this example are called property predicate and has a different set of predicates, see Property predicates.

Logical operation

The and, or and not properties which facilitate explicit logical operation:

{ and: [ P1, P2, P3 ] }
{ or: [ P1, P2, P3 ] }
{ not: [ P1, P2, P3 ] }

are translated as

(P1 and P2 and P3)
(P1 or P2 or P3)
((not P1) and (not P2) and (not P3))

Expansion on multiple values

Some predicates accept array of values, they are generally translated to or, for example:

{ path: [ P1, P2, P3 ] }

are translated as

(path: P1) or (path: P2) or (path: P3)

Some but not all are listed here, for detail consult the JSDoc description for each predicate.

Predicates

contentfragment

{
    contentFragment: true
}

excludepaths

{
    excludePaths: '/foo'
}

Multiple paths are grouped by an and operation:

{
    excludePaths: ['/foo', '/bar']
}

1_excludepaths=/foo
2_excludepaths=/bar

fulltext

{
    fulltext: 'foo'
}

To specify property or sub-node to search in:

{
    fulltext: {
        keyword: 'foo',
        relPath: 'jcr:content/@cq:tags'
    }
}

fulltext=foo
fulltext.relPath=jcr:content/@cq:tags

hasPermission

{
    hasPermission: ['jcr:write', 'jcr:modifyAccessControl']
}

hasPermission=jcr:write,jcr:modifyAccessControl

language

{
    language: 'de'
}

mainasset

{
    mainAsset: true
}

nodename

{
    nodename: 'test*'
}

Multiple nodenames are grouped by an or operation:

{
    nodename: ['foo*', 'bar*']
}

p.or=true
1_nodename=foo*
2_nodename=bar*

notexpired

Not supported.

path

{
    path: '/foo'
}

Multiple paths are grouped by an or operation:

{
    path: ['/foo', '/bar']
}

p.or=true
1_path=/foo
2_path=/bar

To match item with exact path:

{
    path: QueryBuilder.scope.exact('/content/foo')
}

path=/content/foo
path.exact=true

To match only direct children of the path:

{
    path: QueryBuilder.scope.children('/content/foo')
}

path=/content/foo
path.flat=true

Excluding paths is possible by translating into not groups:

{
    path: [
        '/content',
        QueryBuilder.scope.exclude('/content/foo'),
        QueryBuilder.scope.exclude('/content/bar'),
    ]
}

path=/content
1_group.p.not=true
1_group.path=/content/foo
1_group.path.self=true
2_group.p.not=true
2_group.path=/content/bar
2_group.path.self=true

savedquery

Not supported.

similar

Not supported.

type

{
    type: 'cq:Page'
}

Multiple types are grouped by an or operation:

{
    type: ['cq:Page', 'dam:Asset']
}

p.or=true
1_type=cq:Page
2_type=dam:Asset

Property predicates

boolproperty

{
    where: {
        'jcr:isCheckedOut': { eq: true }
    }
}

boolproperty=jcr:isCheckedOut
boolproperty.value=true

Boolean equality predicate can be shorthanded as:

{
    where: {
        'jcr:isCheckedOut': true
    }
}

dateComparison

{
    where: {
        foo: { eq: QueryBuilder.ref('bar', 'date') }
    }
}

dateComparison.property1=foo
dateComparison.property2=bar
dateComparison.operation=equals

Less than (<) and less than or equal (<=) operation are converted to greater than (greater) and greater than or equal (>=) by swapping the properties:

{
    where: {
        foo: { lt: QueryBuilder.ref('bar', 'date') }
    }
}

dateComparison.property1=bar
dateComparison.property2=foo
dateComparison.operation=greater

daterange

{
    where: {
        foo: {
            le: new Date(2021, 10, 1)
        }
    }
}

daterange.property=foo
daterange.upperBound=2021-11-01T00:00:00.000Z
daterange.upperOperation=<=

memberOf

Not supported.

property

{
    where: {
        'jcr:title': { eq: 'bar' }
    }
}

property=jcr:title
property.value=bar
property.operation=equals

Multiple values are supported:

{
    where: {
        'jcr:title': { eq: ['foo', 'bar'] }
    }
}

property=jcr:title
property.1_value=foo
property.2_value=bar
property.operation=equals

Equals operation can be shortand as:

{
    where: {
        'jcr:title': ['foo', 'bar']
    }
}

rangeproperty

{
    where: {
        foo: {
            le: 1
        }
    }
}

rangeproperty.property=foo
rangeproperty.upperBound=1
rangeproperty.upperOperation=<=

relativedaterange

{
    where: {
        'jcr:created': {
            within: ['-1y', '1y']
        }
    }
}

relativedaterange.property=jcr:created
relativedaterange.lowerBound=-1y
relativedaterange.upperBound=1y

tag

Not supported.

tagid

{
    where: {
        'cq:tags': {
            containsAny: ['marketing:interest/product', 'marketing:interest/other']
        }
    }
}

tagid.1_value=marketing:interest/product
tagid.2_value=marketing:interest/other
tagid.property=cq:tags

To require all tags are present, specifies containsAll instead:

{
    where: {
        'cq:tags': {
            containsAll: ['marketing:interest/product', 'marketing:interest/other']
        }
    }
}

tagid.1_value=marketing:interest/product
tagid.2_value=marketing:interest/other
tagid.property=cq:tags
tagid.all=true

tagsearch

{
    where: {
        'cq:tags': {
            keyword: 'foo',
            language: 'de', /* optional */
            fulltext: true  /* optional */
        }
    }
}

tagsearch=foo
tagsearch.property=cq:tags
tagsearch.lang=de
tagsearch.all=true

Predicate group

Groups are generated when or, and and not is specified:

{
    or: [
        { path: '/foo', nodename: 'foo*' },
        { path: '/bar', nodename: 'bar*' }
    ]
}

p.or=true
1_group.path=/foo
1_group.nodename=foo*
2_group.path=/bar
2_group.nodename=bar*

Result controlling parameters

{
    nodeDepth: 1,
    offset: 10,
    limit: 10,
    facets: true,
    guessTotal: true,
    excerpt: true,
    select: '*'
}

p.nodedepth=1
p.offset=10
p.limit=10
p.facets=true
p.guessTotal=true
p.excerpt=true
p.hits=full

Note: p.limit=-1 is always generated if limit is not specified.

To limit only wanted properties in returned result:

{
    select: ['jcr:title', 'jcr:created']
}

p.hits=selective
p.properties=jcr:title jcr:created

Sorting results

{
    orderBy: ['path', 'nodename', 'jcr:title']
}

1_orderby=path
2_orderby=nodename
3_orderby=@jcr:title

Note: Property other than name and nodename are automatically prefixed with @ character.

Explicitly prefix with @ character for reserved property names:

{
    orderBy: ['@path', '@nodename']
}

1_orderby=@path
2_orderby=@nodename

For descending and case-insensitive case:

{
    orderBy: [
        {
            property: 'jcr:title',
            descending: true,
            ignoreCase: true
        }
    ]
}

orderby=@jcr:title
orderby.sort=desc
orderby.case=ignore

Extending query builder

Custom predicate

Support for custom predicates can be achieved by adding new PredicateHandler to QueryBuilder.predicates.

QueryBuilder.predicates.custom = (builder, value, key, p, q) => {
    // key = name of the predicate, "custom" in this case
    // p   = root or nested predicate being processed (p === q for root case)
    // q   = the QueryBuilder object being processed
    builder.append('custom', `Value is ${value}`);
};
new QueryBuilder({
    custom: 1
}).toJSON();

will return:

{
    "custom": "Value is 1",
    "p.limit": "-1"
}

Custom predicates can be type-checked by using type argument when creating QueryBuilder object:

import QueryBuilder from "aem-querybuilder";

interface CustomPredicate extends QueryBuilder.Predicate {
    custom: number
}

// type-checking support for implementing custom predicate handler
(QueryBuilder as QueryBuilder.Static<CustomPredicate>).predicates.custom = (builder, value, key, p, q) => {
    /* ... */
};

// type-checking support for using custom predicate in building query
new QueryBuilder<CustomPredicate>({
    custom: 1
});

Custom property predicate

Custom property predicate can be added by registering a sub-class of PropertyPredicate:

QueryBuilder.PropertyPredicate.register(
    class extends QueryBuilder.PropertyPredicate {
        // parameter name that predicate evaluators in AEM recognizes
        static rootName = 'custom';

        constructor(property, props) {
            // predicate values will be propagated and be accessible from this object
            // through the super constructor
            super(property, props);
        }

        // checks whether this class should be instantiated
        // to process a given predicate
        static shouldProcess(props) {
            return props.customValue !== undefined;
        }

        *generateEntries() {
            yield ['property', this.property];
            yield ['value', `Value is ${this.customValue}`];
        }
    }
);
new QueryBuilder({
    where: {
        property: {
            customValue: 1
        }
    }
}).toJSON();

will return:

{
    "custom.property": "property",
    "custom.value": "Value is 1",
    "p.limit": "-1"
}

Custom property predicates can be type-checked by type argument of the Predicate interface and and the PropertyPredicate base class:

import QueryBuilder from "aem-querybuilder";

interface CustomPropertyPredicateProps {
    customValue: number;
}
type CustomPredicate = QueryBuilder.Predicate<CustomPropertyPredicateProps>;

// type-checking support for implementing custom property predicate
QueryBuilder.PropertyPredicate.register(
    class extends QueryBuilder.PropertyPredicate<CustomPropertyPredicateProps> {
        /* ... */
    }
);

// type-checking support for using custom property predicate in building query
new QueryBuilder<CustomPredicate>({
    where: {
        property: {
            customValue: 1
        }
    }
});

Leveraging existing property predicates

A shorthand property predicates can be implemented with the PropertyPredicate.fromProps utility that generates a normalized list of PropertyPredicate objects from the given predicate.

class CustomPropertyPredicate extends QueryBuilder.PropertyPredicate {
    static rootName = 'custom';

    normalize() {
        return QueryBuilder.PropertyPredicate.fromProps(this.property, {
            /* ... */
        });
    }
}

Expanding to complex conditions

To reach further out, the default behavior of PropertyPredicate.emit can be overriden to emit more complex conditions that fall outside the matching property node itself:

class CustomPropertyPredicate extends QueryBuilder.PropertyPredicate {
    static rootName = 'custom';

    emit(builder) {
        builder.append({
            nodename: 'foo*',
            where: {
                [this.property]: { /* ... */ }
            }
        });
    }
}