Query Builder API query-builder-api

Med Query Builder kan du enkelt hämta innehåll från AEM. Funktionerna visas via ett Java™-API och ett REST-API. I det här dokumentet beskrivs dessa API:er.

Frågebyggaren på serversidan (QueryBuilder) accepterar en frågebeskrivning, skapar och kör en XPath-fråga, kan filtrera resultatuppsättningen och extrahera facets om så önskas.

Frågebeskrivningen är bara en uppsättning predikat (Predicate). Exemplen innehåller ett fulltextpredikat, som motsvarar funktionen jcr:contains() i XPath.

För varje predikattyp finns det en utvärderingskomponent (PredicateEvaluator) som kan hantera det specifika predikatet för XPath, filtrering och facetextrahering. Det är enkelt att skapa anpassade utvärderare, som kopplas in via OSGi-komponentkörningen.

REST API ger åtkomst till samma funktioner via HTTP med svar som skickas i JSON.

Gruppsession gem-session

AEM Gems är en serie tekniska djupdykningar i Adobe Experience Manager som levereras av Adobe experter.

Du kan granska sessionen som är dedikerad till frågebyggaren för en översikt över och användning av verktyget.

Exempelfrågor sample-queries

Dessa exempel anges i Java™-egenskapsformatsnotation. Om du vill använda dem med Java™ API använder du Java™ HashMap som i följande API-exempel.

För JSON-serverns QueryBuilder innehåller varje exempel en exempellänk till en AEM (på standardplatsen http://<host>:<port>). Logga in på AEM innan du använder länkarna.

Returnera alla resultat returning-all-results

Följande fråga returnerar tio resultat (eller för att vara exakt, maximalt tio), men informerar dig om Antal träffar: som är tillgängligt:

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

Samma fråga (med parametern p.limit=-1) returnerar alla resultat (det kan vara ett högt tal beroende på din instans):

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

Använda p.gissningssumma för att returnera resultat using-p-guesstotal-to-return-the-results

Syftet med parametern p.guessTotal är att returnera rätt antal resultat som kan visas genom att kombinera de lägsta möjliga p.offset - och p.limit -värdena. Fördelen med den här parametern är bättre prestanda med stora resultatuppsättningar. Den här parametern undviker också att beräkna hela summan (till exempel anrop av result.getSize()) och att läsa hela resultatuppsättningen, optimerad hela vägen ned till Oak-motorn och indexvärdet. Den här processen kan vara en stor skillnad när det finns hundratusentals resultat, både när det gäller körningstid och minnesanvändning.

Nackdelen med parametern är att användarna inte ser exakt summa. Men du kan ange ett minimiantal som p.guessTotal=1000 så att det alltid läses upp till 1 000. På så sätt får du exakta summor för mindre resultatuppsättningar, men om det är fler kan du bara visa "och mer".

Lägg till p.guessTotal=true i frågan nedan för att se hur den fungerar:

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

Frågan returnerar p.limit-standardvärdet för 10-resultat med en 0-förskjutning:

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

Du kan också använda ett numeriskt värde för att räkna upp till ett anpassat antal maximala resultat. Använd samma fråga som ovan, men ändra värdet för p.guessTotal till 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

Den returnerar ett tal som är lika med standardgränsen på 10 resultat med förskjutningen 0, men visar bara maximalt 50 resultat:

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

Implementera sidnumrering implementing-pagination

Som standard ger Query Builder även antalet träffar. Beroende på den resulterande storleken kan det ta lång tid att fastställa det korrekta antalet genom att kontrollera alla resultat för åtkomstkontroll. För det mesta används summan för att implementera sidnumrering för slutanvändarens användargränssnitt. Eftersom det exakta antalet kan vara långsamt bör du använda funktionen gissningTotal för att implementera sidnumreringen.

Gränssnittet kan till exempel anpassa följande metod:

Använd även guessTotal om användargränssnittet måste använda oändlig rullning för att undvika att Query Builder fastställer det exakta träffantalet.

Hitta burkfiler och beställ dem, senaste först 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

Sök efter alla sidor och sortera dem efter senast ändrade 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

Sök efter alla sidor och sortera dem efter senast ändrade, fallande 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

Fulltextsökning, sorterad efter poäng 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

Sök efter sidor med en viss tagg 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

Använd predikatet tagid som i exemplet om du känner till det explicita tagg-ID:t.

Använd predikatet tag för taggens titelsökväg (utan blanksteg).

I föregående exempel använder du den relativa sökvägen från den noden för tagid.property-predikatet, som är jcr:content/cq:tags, eftersom du söker efter sidor (cq:Page noder). Som standard är tagid.property cq:tags.

Sök i flera banor (med grupper) 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

Den här frågan använder en grupp (med namnet group) som avgränsa deluttryck i en fråga, ungefär som parenteser gör i fler standardnoteringar. Den föregående frågan kan till exempel uttryckas i ett mer välbekant format som:

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

I gruppen i exemplet används predikatet path flera gånger. Om du vill differentiera och ordna de två instanserna av predikatet (ordning krävs för vissa predikat) måste du prefix för predikaten med N_ där N är ordningsindex. I föregående exempel är resultatpredikaten 1_path och 2_path.

p i p.or är en särskild avgränsare som anger att följande (i det här fallet en or) är en -parameter i gruppen, i motsats till ett underpredikat i gruppen, till exempel 1_path.

Om p.or inte anges kombineras alla predikat med AND, vilket innebär att varje resultat måste uppfylla alla predikat.

Sök efter egenskaper search-for-properties

Här söker du efter alla sidor i en viss mall med hjälp av egenskapen 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

Nackdelen är att jcr:content-noderna på sidorna, inte själva sidorna, returneras. Du kan lösa det här problemet genom att söka efter relativ sökväg:

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

Sök efter flera egenskaper search-for-multiple-properties

När du använder egenskapspredikatet flera gånger måste du lägga till nummerprefixen igen:

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

Sök efter flera egenskapsvärden search-for-multiple-property-values

Om du vill undvika stora grupper när du vill söka efter flera värden för en egenskap ("A" or "B" or "C") kan du ange flera värden för predikatet 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

För flervärdesegenskaper kan du även kräva att flera värden matchar ("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

Förfina vad som returneras refining-what-is-returned

Som standard returnerar JSON-servern för QueryBuilder en standarduppsättning med egenskaper för varje nod i sökresultatet (till exempel sökväg, namn och titel). Du kan kontrollera vilka egenskaper som returneras genom att göra något av följande:

Ange

p.hits=full

I så fall inkluderas alla egenskaper för varje nod:

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

Använd

p.hits=selective

Och ange de egenskaper som du vill hämta in

p.properties

Separerat med ett blanksteg:

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

En annan sak du kan göra är att inkludera underordnade noder i svaret i Query Builder. Ange

p.nodedepth=n

Var n är antalet nivåer som du vill att frågan ska returnera. För att en underordnad nod ska kunna returneras måste den anges av egenskapsväljaren

p.hits=full

Exempel:

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

Fler prognoser morepredicates

Mer information om predikat finns på sidan Referens för frågeverktyget.

Du kan också kontrollera JavaScript för PredicateEvaluator-klasserna. Javadoc för dessa klasser innehåller en lista med egenskaper som du kan använda.

Prefixet för klassnamnet (till exempel similar i SimilarityPredicateEvaluator) är klassens huvudegenskap . Den här egenskapen är också namnet på predikatet som ska användas i frågan (i gemener).

För sådana huvudegenskaper kan du förkorta frågan och använda similar=/content/en i stället för den fullständigt kvalificerade varianten similar.similar=/content/en. Det fullständiga, kvalificerade formuläret måste användas för alla icke-huvudsakliga egenskaper i en klass.

Exempel på API-användning för frågebyggaren 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 );
    }

Samma fråga som körs över HTTP med JSON-servern (Query Builder):

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

Lagra och läsa in frågor storing-and-loading-queries

Frågor kan lagras i databasen så att du kan använda dem senare. QueryBuilder tillhandahåller metoden storeQuery med följande signatur:

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

När du använder metoden QueryBuilder#storeQuery lagras den angivna Query i databasen som en fil eller som en egenskap enligt argumentvärdet createFile. I följande exempel visas hur du sparar en Query i sökvägen /mypath/getfiles som en fil:

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

Tidigare lagrade frågor kan läsas in från databasen med metoden QueryBuilder#loadQuery:

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

En Query som sparats till sökvägen /mypath/getfiles kan till exempel läsas in med följande utdrag:

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

Testning och felsökning testing-and-debugging

Om du vill spela upp frågor runt och felsöka frågor i Frågebyggaren kan du använda felsökningskonsolen i Query Builder på

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

Alternativt kan du använda JSON-servern Query Builder på

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

path=/tmp är endast ett exempel.

Allmän felsökning av Recommendations general-debugging-recommendations

Få förklarlig XPath via loggning obtain-explain-able-xpath-via-logging

Förklara alla-frågor under utvecklingscykeln mot målindexuppsättningen.

Hämta förklarlig XPath via Felsökning i Query Builder obtain-explain-able-xpath-via-the-query-builder-debugger

Använd felsökningsprogrammet AEM Query Builder för att generera en förklarlig XPath-fråga.

Felsöka frågor med loggning debugging-queries-with-logging

Loggutdata (INFO-nivå) för frågebyggarimplementeringen när frågan som beskrivs i föregående avsnitt kördes Testing och felsökning:

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

Om du har en fråga med prediktiva utvärderare som filtrerar eller som använder en anpassad ordning efter jämförelseoperatorn, beskrivs den i frågan:

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-länkar javadoc-links