Query Builder-API query-builder-api

De Bouwer van de Vraag biedt een gemakkelijke manier om de inhoudsbewaarplaats van AEM te vragen. De functionaliteit wordt beschikbaar gemaakt via een Java™ API en een REST API. In dit document worden deze API's beschreven.

De server-zijvraagbouwer (QueryBuilder) keurt een vraagbeschrijving goed, creeert en stelt een vraag van XPath in werking, naar keuze filter de resultaatreeks, en ook haalt facetten, indien gewenst.

De vraagbeschrijving is eenvoudig een reeks predikaten (Predicate). Voorbeelden zijn een voorspelling in volledige tekst, die overeenkomt met de functie jcr:contains() in XPath.

Voor elk predikaat type, is er een beoordelaarcomponent (PredicateEvaluator) die weet hoe te om dat specifieke predikaat voor XPath, het filtreren, en facetextractie te behandelen. Het is gemakkelijk om douanebeoordelaars tot stand te brengen, die door componenten OSGi runtime gestopt zijn.

De REST API biedt toegang tot dezelfde functies via HTTP, waarbij reacties worden verzonden in JSON.

Gem-sessie gem-session

AEM Gemsis een reeks technische diepe duiken in Adobe Experience Manager die door de deskundigen van de Adobe worden geleverd.

U kunt de zitting herzien die aan de vraagbouwervoor een overzicht en gebruik van het hulpmiddel wordt gewijd.

Voorbeeldquery's sample-queries

Deze voorbeelden worden gegeven in de stijlnotatie van Java™-eigenschappen. Als u deze wilt gebruiken met de Java™ API, gebruikt u een Java™ HashMap zoals in het volgende API-voorbeeld.

Voor de QueryBuilder JSON Servlet, omvat elk voorbeeld een steekproefverbinding aan een AEM installatie (bij de standaardplaats, http://<host>:<port>). Meld u aan bij uw AEM voordat u deze koppelingen gebruikt.

Alle resultaten retourneren returning-all-results

De volgende vraag keert tien resultaten (of om precies te zijn, een maximum van tien) terug, maar informeert u van het Aantal hits: dat beschikbaar is:

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

De zelfde vraag (met de parameter p.limit=-1) keert alle resultaten terug (het zou een hoog aantal afhankelijk van uw instantie kunnen zijn):

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

Het gebruiken van p.radenTotal om de Resultaten terug te keren using-p-guesstotal-to-return-the-results

Het doel van de parameter p.guessTotal is om het juiste aantal resultaten te retourneren dat kan worden weergegeven door de minimaal haalbare waarden p.offset en p.limit te combineren. Het voordeel van deze parameter is dat de prestaties van grote resultaatsets verbeterd zijn. Met deze parameter wordt ook vermeden dat het volledige totaal wordt berekend (bijvoorbeeld door result.getSize() aan te roepen) en dat de volledige resultaatset wordt gelezen, die tot op de Oak-engine en -index is geoptimaliseerd. Dit proces kan een significant verschil zijn wanneer er honderdduizenden resultaten zijn, zowel in uitvoeringstijd als in geheugengebruik.

Het nadeel van de parameter is dat gebruikers het exacte totaal niet zien. Maar u kunt een minimumaantal zoals p.guessTotal=1000 plaatsen zodat het altijd tot 1000 leest. Op deze manier krijgt u exacte totalen voor kleinere resultaatsets, maar als het meer is, kunt u alleen "en meer" tonen.

Voeg p.guessTotal=true toe aan de onderstaande query om te zien hoe deze werkt:

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

De query retourneert de p.limit standaardwaarde van 10 resultaten met een 0 -verschuiving:

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

U kunt ook een numerieke waarde gebruiken om tot een aangepast aantal maximumresultaten te tellen. Gebruik dezelfde query als hierboven, maar wijzig de waarde van 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

Het keert een aantal de zelfde standaardgrens van 10 resultaten met een 0 compensatie terug, maar toont slechts een maximum van 50 resultaten:

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

Paginering implementeren implementing-pagination

Door gebrek zou de Bouwer van de Vraag ook het aantal treffers verstrekken. Afhankelijk van de resultaatgrootte, zou dit aantal lange tijd kunnen vergen aangezien het bepalen van de nauwkeurige telling het controleren van elk resultaat voor toegangsbeheer impliceert. Meestal wordt het totaal gebruikt om paginering voor de eindgebruiker UI uit te voeren. Aangezien het bepalen van de nauwkeurige telling langzaam kan zijn, wordt geadviseerd dat u de gokTotal eigenschap gebruikt om de paginering uit te voeren.

De interface kan bijvoorbeeld de volgende benadering aanpassen:

Gebruik guessTotal ook in gevallen waarin de gebruikersinterface oneindig schuiven moet gebruiken om te voorkomen dat de Query Builder het exacte aantal treffers bepaalt.

JAR-bestanden zoeken en bestellen, nieuwste eerst find-jar-files-and-order-them-newest-first

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

Alle pagina's zoeken en deze bestellen op Laatst gewijzigd find-all-pages-and-order-them-by-last-modified

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

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

Alle pagina's zoeken en deze bestellen op Laatst gewijzigd, Aflopend find-all-pages-and-order-them-by-last-modified-but-descending

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

fullText-zoekopdracht, besteld door score fulltext-search-ordered-by-score

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

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

Zoeken naar pagina's met een bepaalde tag search-for-pages-tagged-with-a-certain-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

Gebruik tagid predikaat zoals in het voorbeeld als u expliciete markering ID kent.

Gebruik tag prepress voor de weg van de markeringstitel (zonder ruimten).

In het vorige voorbeeld, omdat u naar pagina's (cq:Page knopen) zoekt, gebruik de relatieve weg van die knoop voor tagid.property predikaat, die jcr:content/cq:tags is. De standaardwaarde is tagid.property dan cq:tags .

Meerdere paden zoeken (met groepen) search-under-multiple-paths-using-groups

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

Deze vraag gebruikt a groep (genoemd group), die handelt om subexpressies binnen een vraag te afbakenen, veel zoals haakjes in meer standaardnota's doen. Bijvoorbeeld, zou de vorige vraag in een meer bekende stijl als kunnen worden uitgedrukt:

"Experience" and ("/content/wknd/us/en/magazine" or "/content/wknd/us/en/adventures")

Binnen de groep in het voorbeeld wordt de voorspelling path meerdere keren gebruikt. Als u de twee instanties van de voorspelling wilt onderscheiden en rangschikken (de volgorde is vereist voor sommige voorspellen), moet u de voorspelling voorschrijven met N_ waar N de volgorde-index is. In het vorige voorbeeld zijn de resulterende voorspellingen 1_path en 2_path .

p in p.or is een speciaal afbakening erop wijst die dat wat volgt (in dit geval een or) a parameter van de groep, in tegenstelling tot een subpredikaat van de groep, zoals 1_path is.

Als er geen p.or wordt gegeven, dan zijn alle voorspellingen ANDed samen, dat wil zeggen, elk resultaat moet aan alle voorspellingen voldoen.

Zoeken naar eigenschappen search-for-properties

Hier zoekt u naar alle pagina's van een bepaalde sjabloon met de eigenschap 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

Het nadeel is dat de jcr:content knooppunten van de pagina's, niet de pagina's zelf, worden geretourneerd. U kunt dit probleem oplossen door te zoeken op een relatief pad:

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

Meerdere eigenschappen zoeken search-for-multiple-properties

Wanneer het gebruiken van het bezit voorspelt veelvoudige tijden, moet u de aantalprefixen opnieuw toevoegen:

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

Meerdere eigenschapswaarden zoeken search-for-multiple-property-values

Om grote groepen te vermijden wanneer u naar veelvoudige waarden van een bezit ("A" or "B" or "C") wilt zoeken, kunt u veelvoudige waarden aan property verstrekken predikaat:

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

Voor eigenschappen met meerdere waarden kunt u ook vereisen dat meerdere waarden overeenkomen ("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

Wat wordt geretourneerd, verfijnen refining-what-is-returned

Door gebrek, keert QueryBuilder JSON Servlet een standaardreeks eigenschappen voor elke knoop in het onderzoeksresultaat (bijvoorbeeld, weg, naam, en titel) terug. Als u de controle wilt verkrijgen over de eigenschappen die worden geretourneerd, kunt u een van de volgende handelingen uitvoeren:

Opgeven

p.hits=full

In dat geval worden alle eigenschappen opgenomen voor elk knooppunt:

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

Gebruiken

p.hits=selective

Geef de eigenschappen op die u wilt ophalen

p.properties

Gescheiden door een spatie:

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

Een ander ding u kunt doen is kindknopen in de reactie van de Bouwer van de Vraag omvatten. Opgeven

p.nodedepth=n

Waar n het aantal niveaus is dat u de vraag wilt terugkeren. Als een onderliggende node moet worden geretourneerd, moet deze worden opgegeven door de eigenschappenkiezer

p.hits=full

Voorbeeld:

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

Meer voorspellingen morepredicates

Voor meer predikaten, zie de Vooraf ingestelde pagina van de Verwijzing van de Bouwer van de Vraag.

U kunt Javadoc voor de PredicateEvaluator klassenook controleren. Javadoc voor deze klassen bevat de lijst met eigenschappen die u kunt gebruiken.

De prefix van de klassennaam (bijvoorbeeld, similar in SimilarityPredicateEvaluator) is het belangrijkste bezit van de klasse. Dit bezit is ook de naam van predikaat aan gebruik in de vraag (in kleine letters).

Voor dergelijke belangrijkste eigenschappen kunt u de query verkorten en similar=/content/en gebruiken in plaats van de volledig gekwalificeerde variant similar.similar=/content/en . Het volledig gekwalificeerde formulier moet worden gebruikt voor alle niet-hoofdeigenschappen van een klasse.

Voorbeeld API-gebruik van Query Builder example-query-builder-api-usage

   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 );
    }

Dezelfde query die via HTTP wordt uitgevoerd met de Query Builder (JSON) Servlet:

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

Query's opslaan en laden storing-and-loading-queries

U kunt query's opslaan in de opslagplaats, zodat u ze later kunt gebruiken. In QueryBuilder wordt de methode storeQuery voorzien van de volgende handtekening:

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

Wanneer u de methode QueryBuilder#storeQuerygebruikt, wordt de gegeven Query in de opslagplaats opgeslagen als een bestand of als een eigenschap volgens de argumentwaarde createFile . In het volgende voorbeeld wordt getoond hoe u een Query als bestand opslaat naar het pad /mypath/getfiles :

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

Om het even welke eerder opgeslagen vragen kunnen van de bewaarplaats worden geladen door de QueryBuilder#loadQuerymethode te gebruiken:

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

Een Query opgeslagen naar het pad /mypath/getfiles kan bijvoorbeeld door het volgende fragment worden geladen:

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

Testen en fouten opsporen testing-and-debugging

Voor het spelen rond en het zuiveren van de vragen van de Bouwer van de Vraag, kunt u de debugger console van de Bouwer van de Vraag gebruiken bij

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

Of anders de Query Builder JSON servlet op

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

De path=/tmp is alleen een voorbeeld.

Algemene foutopsporing in Recommendations general-debugging-recommendations

Uitleg XPath verkrijgen via Logging obtain-explain-able-xpath-via-logging

Verklaar alle vragen tijdens de ontwikkelingscyclus tegen de reeks van de doelindex.

Verkrijg Verklarende XPath via Debugger van de Bouwer van de Vraag obtain-explain-able-xpath-via-the-query-builder-debugger

Gebruik debugger van de Bouwer van de Vraag van de AEM om een verklaarbare vraag van XPath te produceren.

Foutopsporing in query's met logboekregistratie debugging-queries-with-logging

De logboekoutput (niveau INFO) van de implementatie van de vraagbouwer wanneer het uitvoeren van de vraag die in de vorige sectie wordt beschreven het Testen en het Zuiveren:

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

Als u een vraag gebruikend predikaat beoordelaars hebt die filter of die een douaneorde door comparator gebruiken, wordt het genoteerd in de vraag:

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-koppelingen javadoc-links