Query Builder offre un modo semplice per eseguire query sull’archivio dei contenuti di AEM. La funzionalità è esposta tramite un’API Java e un’API REST. Questo documento descrive queste API.
Generatore di query lato server (QueryBuilder
) accetta una descrizione della query, crea ed esegue una query XPath, filtra facoltativamente il set di risultati e, se necessario, estrae anche i facet.
La descrizione della query è semplicemente un insieme di predicati (Predicate
). Gli esempi includono un predicato full-text che corrisponde al jcr:contains()
in XPath.
Per ogni tipo di predicato, esiste un componente valutatore (PredicateEvaluator
) che sa come gestire quel predicato specifico per XPath, filtraggio ed estrazione del facet. È molto facile creare valutatori personalizzati, che sono collegati tramite il runtime del componente OSGi.
L’API REST consente di accedere esattamente alle stesse funzioni tramite HTTP e le risposte vengono inviate in JSON.
L’API QueryBuilder viene creata utilizzando l’API JCR. Puoi anche eseguire query sul JCR AEM utilizzando l'API JCR da un bundle OSGi. Per informazioni, consulta Query dei dati di Adobe Experience Manager tramite l’API JCR.
AEM gemme è una serie di approfondimenti tecnici su Adobe Experience Manager forniti da esperti di Adobe.
È possibile controlla la sessione dedicata al generatore di query per una panoramica e l’utilizzo dello strumento.
Questi esempi sono forniti nella notazione dello stile delle proprietà Java. Per utilizzarli con l’API Java, utilizza un HashMap
come nell’esempio di API che segue.
Per QueryBuilder
Servlet JSON, ogni esempio include un collegamento di esempio a un’installazione AEM (nella posizione predefinita, http://<host>:<port>
). Prima di utilizzare questi collegamenti, è necessario accedere all’istanza AEM.
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
Per visualizzare i dati JSON restituiti nel browser, potresti voler usare un plug-in come JSONView per Firefox.
La seguente query restituisce dieci risultati (o per essere precisi un massimo di dieci), ma informarti Numero di hit: che sono 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
) restituisce tutti i risultati (potrebbe essere un numero elevato a seconda dell’istanza):
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
Lo scopo del p.guessTotal
è quello di restituire il numero appropriato di risultati che possono essere mostrati combinando il minimo fattibile p.offset
e p.limit
valori. Il vantaggio di utilizzare questo parametro è il miglioramento delle prestazioni con grandi set di risultati. In questo modo si evita di calcolare l'intero totale (ad es. result.getSize()
) e lettura dell'intero set di risultati, ottimizzato fino al motore OAK e indice. Questa può essere una differenza significativa quando ci sono centinaia di migliaia di risultati, sia in termini di tempo di esecuzione che di utilizzo della memoria.
Lo svantaggio del parametro è che gli utenti non vedono il totale esatto. Ma puoi impostare un numero minimo come p.guessTotal=1000
quindi sarà sempre letto fino a 1000, quindi si ottengono i totali esatti per set di risultati più piccoli, ma se è più di questo, si può 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à la variabile p.limit
predefinito 10
risultati con un 0
offset:
"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. Utilizza la stessa query di cui sopra, ma modifica il valore di p.guessTotal
a 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
Restituisce un numero con lo stesso limite predefinito di 10 risultati con un offset 0, ma visualizza solo un massimo di 50 risultati:
"success": true,
"results": 10,
"total": 50,
"more": true,
"offset": 0,
Per impostazione predefinita, il Generatore di query fornisce anche il numero di hit. A seconda della dimensione del risultato, questo potrebbe richiedere molto tempo, in quanto la determinazione del conteggio accurato comporta il controllo di ogni risultato per il controllo degli accessi. Per lo più, il totale viene utilizzato per implementare l’impaginazione per l’interfaccia utente finale. Poiché la determinazione del conteggio esatto può essere lenta, si consiglia di utilizzare la funzione guessTotal per implementare l’impaginazione.
Ad esempio, l’interfaccia utente può adattare il seguente approccio:
Ottieni e visualizza il conteggio accurato del numero di hit totali (SearchResult.getTotalMatches() o totale querybuilder.json
risposte) sono inferiori o uguali a 100;
Imposta guessTotal
a 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 l’impaginazione per le tre pagine successive. Puoi anche utilizzare questa implementazione per visualizzare un testo descrittivo come "43 risultati trovati".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ò visualizzare fino a dieci pagine come parte della prima pagina e fornire impaginazione per le dieci pagine successive. È inoltre possibile utilizzare questa opzione per visualizzare un testo come "più di 100 risultati trovati". Man mano che l’utente passa alle successive chiamate effettuate al Generatore di query, il limite di guessTotal
e anche del offset
e limit
Parametri.guessTotal
Deve essere utilizzato anche nei casi in cui l’interfaccia utente deve utilizzare lo scorrimento infinito, per evitare che Query Builder determini l’esatto numero di hit.
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
http://<host>:<port>/bin/querybuilder.json?type=cq:Page&orderby=@jcr:content/cq:lastModified
type=cq:Page
orderby=@jcr:content/cq:lastModified
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
http://<host>:<port>/bin/querybuilder.json?fulltext=Management&orderby=@jcr:score&orderby.sort=desc
fulltext=Management
orderby=@jcr:score
orderby.sort=desc
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
Utilizza la tagid
predicare come nell'esempio se conosci l'ID tag esplicito.
Utilizza la tag
predicato per il percorso del titolo del tag (senza spazi).
Perché, nell’esempio precedente, stai cercando le pagine (cq:Page
nodi), è necessario utilizzare il percorso relativo da quel nodo per tagid.property
predicato, ovvero jcr:content/cq:tags
. Per impostazione predefinita, la tagid.property
semplicemente cq:tags
.
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 fanno le parentesi nelle notazioni più standard. Ad esempio, la query precedente potrebbe essere espressa in uno stile più familiare come:
"Experience" and ("/content/wknd/us/en/magazine" or "/content/wknd/us/en/adventures")
All’interno del gruppo nell’esempio, il path
Il predicato viene utilizzato più volte. Per differenziare e ordinare le due istanze del predicato (l’ordinamento è necessario 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
.
La p
in p.or
è un delimitatore speciale che indica quanto segue (in questo caso un or
) è un parameter del gruppo, invece di un subpredicato del gruppo, come 1_path
.
Se no p.or
viene dato allora tutti i predicati sono ANDed insieme, cioè, ogni risultato deve soddisfare tutti i predicati.
Non è possibile utilizzare lo stesso prefisso numerico in una singola query, anche per predicati diversi.
Qui stai cercando tutte le pagine di un dato modello, utilizzando cq:template
proprietà:
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 che il jcr:content
vengono restituiti i nodi delle pagine, non le pagine stesse. Per risolvere questo problema, è possibile eseguire ricerche per 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
Quando si utilizza il predicato proprietà più volte, è 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
Per evitare grandi gruppi quando si desidera cercare più valori di una proprietà ("A" or "B" or "C"
), è possibile fornire più valori al property
predicato:
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à con più valori, puoi 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
Per impostazione predefinita, il servlet JSON di QueryBuilder restituisce un set predefinito di proprietà per ciascun nodo nel risultato della ricerca (ad esempio percorso, nome, titolo, ecc.). Per ottenere il controllo sulle proprietà restituite, è possibile effettuare una delle seguenti operazioni:
Specifica
p.hits=full
in tal caso tutte le proprietà verranno incluse per ogni 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 specifica le proprietà che desideri inserire
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
Un’altra cosa che è possibile fare è includere nodi figlio nella risposta di Query Builder. Per eseguire questa operazione è necessario specificare
p.nodedepth=n
dove n
è il numero di livelli che la query deve restituire. Tieni presente che 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
Per ulteriori predicati, consulta la sezione Pagina di riferimento del predicato di Query Builder.
Puoi anche controllare la Javadoc per PredicateEvaluator
classi. Javadoc per queste classi contiene l'elenco delle proprietà che è possibile utilizzare.
Prefisso del nome della classe (ad esempio, similar
in SimilarityPredicateEvaluator
) è proprietà principale della classe. Questa proprietà è anche il nome del predicato da utilizzare nella query (in minuscolo).
Per tali proprietà principali, è possibile accorciare 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.
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 utilizzando 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
Le query possono essere archiviate nell’archivio in modo da poterle utilizzare in un secondo momento. La QueryBuilder
fornisce storeQuery
metodo con la firma seguente:
void storeQuery(Query query, String path, boolean createFile, Session session) throws RepositoryException, IOException;
Quando utilizzi QueryBuilder#storeQuery
il metodo Query
viene memorizzato nell'archivio come file o come proprietà in base al createFile
valore dell'argomento. L’esempio seguente mostra come salvare un Query
al percorso /mypath/getfiles
come file:
builder.storeQuery(query, "/mypath/getfiles", true, session);
Qualsiasi query precedentemente archiviata può essere caricata dal repository utilizzando QueryBuilder#loadQuery
metodo:
Query loadQuery(String path, Session session) throws RepositoryException, IOException
Ad esempio, un Query
memorizzato nel percorso /mypath/getfiles
può essere caricato dal seguente snippet:
Query loadedQuery = builder.loadQuery("/mypath/getfiles", session);
Per riprodurre e eseguire il debug delle query di Query Builder, puoi utilizzare la console di debug di Query Builder in
http://<host>:<port>/libs/cq/search/content/querydebug.html
o in alternativa il servlet JSON di Query Builder all’indirizzo
http://<host>:<port>/bin/querybuilder.json?path=/tmp
path=/tmp
è solo un esempio.
Spiegare tutto le query durante il ciclo di sviluppo rispetto all'indice di destinazione impostato.
https://<host>:<port>/system/console/slinglog
. Crea un nuovo logger per com.day.cq.search.impl.builder.QueryImpl
a DEBUG.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"))]
Utilizza il debugger di Query Builder AEM per generare una query XPath spiegabile.
Le query non Query Builder (XPath, JCR-SQL2) possono essere fornite direttamente a Explain Query.
La configurazione dei logger è descritta nel documento Registrazione.
L'output di log (livello INFO) dell'implementazione del generatore di query durante l'esecuzione della query descritta nella sezione precedente Test e debug:
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 disponi di una query che utilizza valutatori predicati che filtrano o utilizzano un ordine personalizzato per comparatore, questa operazione verrà rilevata anche 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 | API Query Builder di base e 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 | Valutatori del predicato |
com.day.cq.search.facets.extractor | Estrattori di sfaccettature (per valutatori) |
com.day.cq.search.writer | Redattore di hit di risultati JSON per il servlet di Query Builder (/bin/querybuilder.json ) |