API Query Builder

Query Builder offre un modo semplice per interrogare l'archivio dei contenuti di AEM. La funzionalità è esposta tramite un'API Java e un'API REST. Questo documento descrive queste API.

Il generatore di query lato server (QueryBuilder) accetta una descrizione della query, crea ed esegue una query XPath, eventualmente applica un filtro al set di risultati e, se necessario, estrae anche i facet.

La descrizione della query è semplicemente un insieme di predicati (Predicate). Alcuni esempi includono un predicato full-text, che corrisponde alla funzione jcr:contains() in XPath.

Per ciascun tipo di predicato, è presente un componente valutatore (PredicateEvaluator) in grado di gestire tale predicato specifico per XPath, filtraggio ed estrazione dei facet. È molto facile creare valutatori personalizzati, che vengono collegati tramite il runtime dei componenti OSGi.

L'API REST fornisce l'accesso esattamente alle stesse funzionalità tramite HTTP, con le risposte inviate in JSON.

NOTA

L'API QueryBuilder viene creata utilizzando l'API JCR. Potete anche eseguire una query sul JCR AEM utilizzando l'API JCR da un bundle OSGi. Per informazioni, vedere Query dei dati Adobe Experience Manager tramite l'API JCR.

Sessione Gem

AEM Gemsis una serie di approfondimenti tecnici in Adobe Experience Manager forniti da esperti Adobe.

È possibile rivedere la sessione dedicata al generatore di query per una panoramica e l'utilizzo dello strumento.

Query di esempio

Questi esempi sono riportati nella notazione dello stile delle proprietà Java. Per utilizzarli con l'API Java, utilizzate Java HashMap come nell'esempio di API che segue.

Per il Servlet QueryBuilder JSON, ogni esempio include un collegamento di esempio a un'installazione AEM (nel percorso predefinito, http://<host>:<port>). Prima di usare questi collegamenti è necessario accedere all'istanza AEM.

ATTENZIONE

Per impostazione predefinita, il servlet JSON del generatore di query visualizza un massimo di 10 hit.

L'aggiunta del seguente parametro consente al servlet di visualizzare tutti i risultati della query:

p.limit=-1

NOTA

Per visualizzare i dati JSON restituiti nel browser, potresti voler usare un plug-in come JSONView per Firefox.

Restituzione di tutti i risultati

La seguente query restituisce dieci risultati (o per essere precisi, un massimo di dieci), ma vi informa del Numero di hit: effettivamente disponibili:

http://<host>:<port>/bin/querybuilder.json?path=/content&1_property=sling:resourceType&1_property.value=wknd/components/structure/page&1_property.operation=like&orderby=path

path=/content
1_property=sling:resourceType
1_property.value=wknd/components/structure/page
1_property.operation=like
orderby=path

La stessa query (con il parametro p.limit=-1) restituirà tutti i risultati (a seconda dell'istanza potrebbe essere un numero elevato):

http://<host>:<port>/bin/querybuilder.json?path=/content&1_property=sling:resourceType&1_property.value=wknd/components/structure/page&1_property.operation=like&orderby=path&p.limit=-1

path=/content
1_property=sling:resourceType
1_property.value=wknd/components/structure/page
1_property.operation=like
p.limit=-1
orderby=path

Utilizzo di p.impressionTotal per restituire i risultati

Lo scopo del parametro p.guessTotal è quello di restituire il numero appropriato di risultati che possono essere mostrati combinando i valori minimi vitali p.offset e p.limit. Il vantaggio di utilizzare questo parametro è rappresentato da prestazioni migliori con set di risultati di grandi dimensioni. In questo modo si evita di calcolare il totale totale (ad es. result.getSize()) e di leggere l'intero set di risultati, ottimizzato fino al motore OAK e all'indice. Questa differenza può essere significativa in presenza di centinaia di migliaia di risultati, sia in termini di tempo di esecuzione che di utilizzo della memoria.

Lo svantaggio per il parametro è che gli utenti non vedono il totale esatto. È tuttavia possibile impostare un numero minimo come p.guessTotal=1000 in modo che possa sempre leggere fino a 1000, quindi si ottengono i totali esatti per i set di risultati più piccoli, ma se è più di questo, è possibile solo mostrare "e più".

Aggiungi p.guessTotal=true alla query seguente per vedere come funziona:

http://<host>:<port>/bin/querybuilder.json?path=/content&1_property=sling:resourceType&1_property.value=wknd/components/structure/page&1_property.operation=like&p.guessTotal=true&orderby=path

path=/content
1_property=sling:resourceType
1_property.value=wknd/components/structure/page
1_property.operation=like
p.guessTotal=true
orderby=path

La query restituirà il valore predefinito p.limit di 10 risultati con un offset 0:

"success": true,
"results": 10,
"total": 10,
"more": true,
"offset": 0,

È inoltre possibile utilizzare un valore numerico per contare fino a un numero personalizzato di risultati massimi. Utilizzate la stessa query di cui sopra, ma modificate il valore di p.guessTotal in 50:

http://<host>:<port>/bin/querybuilder.json?path=/content&1_property=sling:resourceType&1_property.value=wknd/components/structure/page&1_property.operation=like&p.guessTotal=50&orderby=path

Verrà restituito un numero con lo stesso limite predefinito di 10 risultati con un offset pari a 0, ma verranno visualizzati solo 50 risultati:

"success": true,
"results": 10,
"total": 50,
"more": true,
"offset": 0,

Implementazione impaginazione

Per impostazione predefinita, Query Builder fornisce anche il numero di hit. A seconda della dimensione del risultato, questo potrebbe richiedere molto tempo, poiché per determinare il conteggio accurato è necessario controllare ogni risultato per il controllo dell'accesso. La maggior parte del totale viene utilizzata per implementare l'impaginazione per l'interfaccia utente finale. Poiché determinare il conteggio esatto può essere lento, si consiglia di utilizzare la funzione approssimativaTotale per implementare l'impaginazione.

Ad esempio, l’interfaccia utente può adattare il seguente approccio:

  • Ottenere e visualizzare il conteggio accurato del numero totale di hit (SearchResult.getTotalMatches() o totale nella querybuilder.json risposta) è minore o uguale a 100;

  • Impostate guessTotal su 100 durante la chiamata al Generatore di query.

  • La risposta può avere il seguente risultato:

    • total=43, more=false - Indica che il numero totale di hit è 43. L’interfaccia utente può visualizzare fino a dieci risultati nella prima pagina e fornire impaginazione per le tre pagine successive. Potete inoltre utilizzare questa implementazione per visualizzare un testo descrittivo come "43 Results found".
    • total=100, more=true - Indica che il numero totale di hit è maggiore di 100 e che il conteggio esatto non è noto. L’interfaccia utente può essere visualizzata fino a dieci nella prima pagina e fornire impaginazione per le dieci pagine successive. È inoltre possibile utilizzare questa opzione per visualizzare un testo come "oltre 100 risultati trovati". Man mano che l'utente passa alle pagine successive, le chiamate effettuate al Generatore di query aumentano il limite di guessTotal e anche dei parametri offset e limit.

guessTotal dovrebbe essere utilizzato anche nei casi in cui l'interfaccia utente deve utilizzare lo scorrimento infinito, per evitare che il Generatore di query determini l'esatto numero di hit.

Trova file Jar e ordinali, il più recente

http://<host>:<port>/bin/querybuilder.json?type=nt:file&nodename=*.jar&orderby=@jcr:content/jcr:lastModified&orderby.sort=desc

type=nt:file
nodename=*.jar
orderby=@jcr:content/jcr:lastModified
orderby.sort=desc

Trova tutte le pagine e ordinale per ultima modifica

http://<host>:<port>/bin/querybuilder.json?type=cq:Page&orderby=@jcr:content/cq:lastModified

type=cq:Page
orderby=@jcr:content/cq:lastModified

Trova tutte le pagine e ordinale per ultima modifica, decrescente

http://<host>:<port>/bin/querybuilder.json?type=cq:Page&orderby=@jcr:content/cq:lastModified&orderby.sort=desc

type=cq:Page
orderby=@jcr:content/cq:lastModified
orderby.sort=desc

Ricerca full-text, ordinata per punteggio

http://<host>:<port>/bin/querybuilder.json?fulltext=Management&orderby=@jcr:score&orderby.sort=desc

fulltext=Management
orderby=@jcr:score
orderby.sort=desc

Cerca pagine con un determinato tag

http://<host>:<port>/bin/querybuilder.json?type=cq:Page&tagid=wknd:activity/cycling&tagid.property=jcr:content/cq:tags

type=cq:Page
tagid=wknd:activity/cycling
tagid.property=jcr:content/cq:tags

Utilizzate il predicato tagid come nell'esempio, se conoscete l'ID di tag esplicito.

Utilizzate il predicato tag per il percorso del titolo del tag (senza spazi).

Poiché, nell'esempio precedente, si stanno cercando pagine (cq:Page nodi), è necessario utilizzare il percorso relativo da tale nodo per il predicato tagid.property, che è jcr:content/cq:tags. Per impostazione predefinita, il tagid.property è semplicemente cq:tags.

Cerca più percorsi (tramite gruppi)

http://<host>:<port>/bin/querybuilder.json?fulltext=Experience&group.1_path=/content/wknd/us/en/magazine&group.2_path=/content/wknd/us/en/adventures&group.p.or=true

fulltext=Experience
group.p.or=true
group.1_path=/content/wknd/us/en/magazine
group.2_path=/content/wknd/us/en/adventures

Questa query utilizza un gruppo (denominato group) che agisce per delimitare le sottoespressioni all'interno di una query, come accade per le parentesi in notazioni più standard. Ad esempio, la query precedente potrebbe essere espressa in uno stile più familiare come:

"Experience" and ("/content/wknd/us/en/magazine?lang=it" or "/content/wknd/us/en/adventures?lang=it")

All'interno del gruppo nell'esempio, il predicato path viene utilizzato più volte. Per distinguere e ordinare le due istanze del predicato (l'ordine è richiesto per alcuni predicati), è necessario preimpostare i predicati con N_ dove N è l'indice di ordinamento. Nell'esempio precedente, i predicati risultanti sono 1_path e 2_path.

p in p.or è un delimitatore speciale che indica che ciò che segue (in questo caso un or) è un parametro del gruppo, a differenza di un subpredicato del gruppo, come 1_path.

Se non viene fornito alcun valore p.or, tutti i predicati vengono inseriti insieme, ovvero ogni risultato deve soddisfare tutti i predicati.

NOTA

Non è possibile utilizzare lo stesso prefisso numerico in una singola query, anche per diversi predicati.

Cerca proprietà

Qui state cercando tutte le pagine di un dato modello, utilizzando la proprietà cq:template:

http://<host>:<port>/bin/querybuilder.json?property=cq%3atemplate&property.value=%2fconf%2fwknd%2fsettings%2fwcm%2ftemplates%2fadventure-page-template&type=cq%3aPageContent

type=cq:PageContent
property=cq:template
property.value=/conf/wknd/settings/wcm/templates/adventure-page-template

Questo ha lo svantaggio di restituire i nodi jcr:content delle pagine, non le pagine stesse. Per risolvere questo problema, potete eseguire una ricerca in base al percorso relativo:

http://<host>:<port>/bin/querybuilder.json?property=jcr%3acontent%2fcq%3atemplate&property.value=%2fconf%2fwknd%2fsettings%2fwcm%2ftemplates%2fadventure-page-template&type=cq%3aPage

type=cq:Page
property=jcr:content/cq:template
property.value=/conf/wknd/settings/wcm/templates/adventure-page-template

Ricerca di più proprietà

Quando si utilizza più volte il predicato delle proprietà, è necessario aggiungere di nuovo i prefissi numerici:

http://<host>:<port>/bin/querybuilder.json?1_property=jcr%3acontent%2fcq%3atemplate&1_property.value=%2fconf%2fwknd%2fsettings%2fwcm%2ftemplates%2fadventure-page-template&2_property=jcr%3acontent%2fjcr%3atitle&2_property.value=Cycling%20Tuscany&type=cq%3aPage

type=cq:Page
1_property=jcr:content/cq:template
1_property.value=/conf/wknd/settings/wcm/templates/adventure-page-template
2_property=jcr:content/jcr:title
2_property.value=Cycling Tuscany

Ricerca di più valori di proprietà

Per evitare gruppi di grandi dimensioni quando si desidera cercare più valori di una proprietà ("A" or "B" or "C"), è possibile fornire più valori al predicato property:

http://<host>:<port>/bin/querybuilder.json?property=jcr%3atitle&property.1_value=Cycling%20Tuscany&property.2_value=Ski%20Touring&property.3_value=Whistler%20Mountain%20Biking

property=jcr:title
property.1_value=Cycling Tuscany
property.2_value=Ski Touring
property.3_value=Whistler Mountain Biking

Per le proprietà multivalore, potete anche richiedere che più valori corrispondano ("A" and "B" and "C"):

http://<host>:<port>/bin/querybuilder.json?property=jcr%3atitle&property.and=true&property.1_value=Cycling%20Tuscany&property.2_value=Ski%20Touring&property.3_value=Whistler%20Mountain%20Biking

property=jcr:title
property.and=true
property.1_value=Cycling Tuscany
property.2_value=Ski Touring
property.3_value=Whistler Mountain Biking

Ottimizzazione dei valori restituiti

Per impostazione predefinita, il servlet JSON QueryBuilder restituirà un set predefinito di proprietà per ciascun nodo nel risultato della ricerca (ad esempio percorso, nome, titolo, ecc.). Per controllare quali proprietà vengono restituite, è possibile effettuare una delle seguenti operazioni:

Specifica

p.hits=full

in tal caso tutte le proprietà saranno incluse per ciascun nodo:

http://<host>:<port>/bin/querybuilder.json?p.hits=full&property=jcr%3atitle&property.value=Cycling%20Tuscany

property=jcr:title
property.value=Cycling Tuscany
p.hits=full

Utilizzo

p.hits=selective

e specificare le proprietà in cui si desidera accedere

p.properties

separati da uno spazio:

http://<host>:<port>/bin/querybuilder.json?p.hits=selective&p.properties=sling%3aresourceType%20jcr%3aprimaryType&property=jcr%3atitle&property.value=Cycling%20Tuscany

property=jcr:title
property.value=Cycling Tuscany
p.hits=selective
p.properties=sling:resourceType jcr:primaryType

È inoltre possibile includere nodi secondari nella risposta di Query Builder. A tal fine è necessario specificare

p.nodedepth=n

dove n è il numero di livelli che si desidera che venga restituito dalla query. Per restituire un nodo figlio, è necessario specificarlo dal selettore delle proprietà

p.hits=full

Esempio:

http://<host>:<port>/bin/querybuilder.json?p.hits=full&p.nodedepth=5&property=jcr%3atitle&property.value=Cycling%20Tuscany

property=jcr:title
property.value=Cycling Tuscany
p.hits=full
p.nodedepth=5

Altri predicati

Per ulteriori predicati, consultate la pagina Riferimento predicato Generatore di query.

È inoltre possibile controllare il codice Javadoc per le classi PredicateEvaluator. Javadoc per queste classi contiene l'elenco delle proprietà utilizzabili.

Il prefisso del nome della classe (ad esempio, similar in SimilarityPredicateEvaluator) è la proprietà principal della classe. Questa proprietà è anche il nome del predicato da utilizzare nella query (in lettere minuscole).

Per tali proprietà principali, è possibile ridurre la query e utilizzare similar=/content/en invece della variante completa similar.similar=/content/en. Il modulo completo deve essere utilizzato per tutte le proprietà non principali di una classe.

Esempio di utilizzo dell'API Query Builder

   String fulltextSearchTerm = "WKND";

    // create query description as hash map (simplest way, same as form post)
    Map<String, String> map = new HashMap<String, String>();

// create query description as hash map (simplest way, same as form post)
    map.put("path", "/content");
    map.put("type", "cq:Page");
    map.put("group.p.or", "true"); // combine this group with OR
    map.put("group.1_fulltext", fulltextSearchTerm);
    map.put("group.1_fulltext.relPath", "jcr:content");
    map.put("group.2_fulltext", fulltextSearchTerm);
    map.put("group.2_fulltext.relPath", "jcr:content/@cq:tags");

    // can be done in map or with Query methods
    map.put("p.offset", "0"); // same as query.setStart(0) below
    map.put("p.limit", "20"); // same as query.setHitsPerPage(20) below

    Query query = builder.createQuery(PredicateGroup.create(map), session);
    query.setStart(0);
    query.setHitsPerPage(20);

    SearchResult result = query.getResult();

    // paging metadata
    int hitsPerPage = result.getHits().size(); // 20 (set above) or lower
    long totalMatches = result.getTotalMatches();
    long offset = result.getStartIndex();
    long numberOfPages = totalMatches / 20;

    //Place the results in XML to return to client
    DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
    DocumentBuilder builder = factory.newDocumentBuilder();
    Document doc = builder.newDocument();

    //Start building the XML to pass back to the AEM client
    Element root = doc.createElement( "results" );
    doc.appendChild( root );

    // iterating over the results
    for (Hit hit : result.getHits()) {
       String path = hit.getPath();

      //Create a result element
      Element resultel = doc.createElement( "result" );
      root.appendChild( resultel );

      Element pathel = doc.createElement( "path" );
      pathel.appendChild( doc.createTextNode(path ) );
      resultel.appendChild( pathel );
    }

La stessa query eseguita su HTTP tramite il servlet Query Builder (JSON):

http://<host>:<port>/bin/querybuilder.json?path=/content&type=cq:Page&group.p.or=true&group.1_fulltext=WKND&group.1_fulltext.relPath=jcr:content&group.2_fulltext=WKND&group.2_fulltext.relPath=jcr:content/@cq:tags&p.offset=0&p.limit=20

Memorizzazione e caricamento di query

Le query possono essere memorizzate nella directory archivio in modo da poterle utilizzare in un secondo momento. QueryBuilder fornisce il metodo storeQuery con la seguente firma:

void storeQuery(Query query, String path, boolean createFile, Session session) throws RepositoryException, IOException;

Quando si utilizza il metodo QueryBuilder#storeQuery, l'elemento Query specificato viene memorizzato nell'archivio come file o come proprietà in base al valore dell'argomento createFile. L'esempio seguente mostra come salvare un Query nel percorso /mypath/getfiles come file:

builder.storeQuery(query, "/mypath/getfiles", true, session);

Eventuali query precedentemente archiviate possono essere caricate dall'archivio utilizzando il metodo QueryBuilder#loadQuery:

Query loadQuery(String path, Session session) throws RepositoryException, IOException

Ad esempio, un Query memorizzato nel percorso /mypath/getfiles può essere caricato dal frammento seguente:

Query loadedQuery = builder.loadQuery("/mypath/getfiles", session);

Test e debug

Per la riproduzione e il debug delle query di Query Builder, potete utilizzare la console di debug di Query Builder in

http://<host>:<port>/libs/cq/search/content/querydebug.html

oppure, in alternativa, il servlet JSON di Query Builder all'indirizzo

http://<host>:<port>/bin/querybuilder.json?path=/tmp

path=/tmp è solo un esempio.

Debug generale Recommendations

Ottenere XPath spiegabile tramite la registrazione

Spiegare le query all durante il ciclo di sviluppo rispetto all'indice di destinazione impostato.

  1. Abilitare i registri DEBUG per QueryBuilder per ottenere la query XPath sottostante spiegabile
    • Accedi a https://<host>:<port>/system/console/slinglog. Create un nuovo logger per com.day.cq.search.impl.builder.QueryImpl in DEBUG.
  2. Una volta attivato DEBUG per la classe sopra riportata, i registri visualizzeranno l'XPath generato da Query Builder.
  3. Copiate la query XPath dalla voce di registro per la query di Query Builder associata, ad esempio:
    • com.day.cq.search.impl.builder.QueryImpl XPath query: /jcr:root/content//element(*, cq:Page)[(jcr:contains(jcr:content, "WKND") or jcr:contains(jcr:content/@cq:tags, "WKND"))]
  4. Incollate la query XPath in Spiega query come XPath per ottenere il piano di query.

Ottenete XPath spiegabile tramite Query Builder Debugger

Utilizzate AEM Query Builder Debugger per generare una query XPath esplorabile.

Debugger Query Builder

  1. Fornisce la query Query Builder nel debugger di Query Builder
  2. Eseguire la ricerca
  3. Ottenete l'XPath generato
  4. Incollare la query XPath in Explain Query come XPath per ottenere il piano di query
NOTA

Le query non Query Builder (XPath, JCR-SQL2) possono essere fornite direttamente a Explain Query.

Debug di query con registrazione

NOTA

La configurazione dei logger è descritta nel documento Logging.

L'output di registro (livello INFO) dell'implementazione del generatore di query durante l'esecuzione della query descritta nella sezione precedente Test and Debugging:

com.day.cq.search.impl.builder.QueryImpl executing query (predicate tree):
null=group: limit=20, offset=0[
    {group=group: or=true[
        {1_fulltext=fulltext: fulltext=WKND, relPath=jcr:content}
        {2_fulltext=fulltext: fulltext=WKND, relPath=jcr:content/@cq:tags}
    ]}
    {path=path: path=/content}
    {type=type: type=cq:Page}
]
com.day.cq.search.impl.builder.QueryImpl XPath query: /jcr:root/content//element(*, cq:Page)[(jcr:contains(jcr:content, "WKND") or jcr:contains(jcr:content/@cq:tags, "WKND"))]
com.day.cq.search.impl.builder.QueryImpl no filtering predicates
com.day.cq.search.impl.builder.QueryImpl query execution took 69 ms

Se si dispone di una query utilizzando i valutatori predicati che filtrano o utilizzano un ordine personalizzato per confronto, anche questo verrà notato nella query:

com.day.cq.search.impl.builder.QueryImpl executing query (predicate tree):
null=group: [
    {nodename=nodename: nodename=*.jar}
    {orderby=orderby: orderby=@jcr:content/jcr:lastModified}
    {type=type: type=nt:file}
]
com.day.cq.search.impl.builder.QueryImpl custom order by comparator: jcr:content/jcr:lastModified
com.day.cq.search.impl.builder.QueryImpl XPath query: //element(*, nt:file)
com.day.cq.search.impl.builder.QueryImpl filtering predicates: {nodename=nodename: nodename=*.jar}
com.day.cq.search.impl.builder.QueryImpl query execution took 272 ms
Javadoc Descrizione
com.day.cq.search Query Builder di base e API Query
com.day.cq.search.result API dei risultati
com.day.cq.search.facets Facet
com.day.cq.search.facets.bukets Punti (contenuti nei facet)
com.day.cq.search.eval Predicate Valutatori
com.day.cq.search.facets.extrattori Estrattori di sfaccettature (per valutatori)
com.day.cq.search.writer Scrittore di risultati JSON per il servlet Query Builder (/bin/querybuilder.json)

In questa pagina