1"use strict";(globalThis.webpackChunkdocusaurus_docs=globalThis.webpackChunkdocusaurus_docs||[]).push([[15284],{28453:(e,n,a)=>{a.d(n,{R:()=>c,x:()=>t});var s=a(96540);const i={},r=s.createContext(i);function c(e){const n=s.useContext(r);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function t(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:c(e.components),s.createElement(r.Provider,{value:n},e.children)}},35827:(e,n,a)=>{a.r(n),a.d(n,{assets:()=>l,contentTitle:()=>t,default:()=>h,frontMatter:()=>c,metadata:()=>s,toc:()=>d});const s=JSON.parse('{"id":"dql/query/facets","title":"Querying Facets","description":"This page covers how to query and filter using facets in DQL. For an introduction to what facets are and how to create them, see Facets in Schema.","source":"@site/docs_versioned_docs/version-v25.1/dql/query/facets.md","sourceDirName":"dql/query","slug":"/dql/query/facets","permalink":"/v25.1/dql/query/facets","draft":false,"unlisted":false,"editUrl":"https://github.com/dgraph-io/dgraph-docs/edit/main/docusaurus-docs/docs/dql/query/facets.md","tags":[],"version":"v25.1","frontMatter":{"title":"Querying Facets"},"sidebar":"docsSidebar","previous":{"title":"Query Structure","permalink":"/v25.1/dql/query/dql-query"},"next":{"title":"Functions","permalink":"/v25.1/dql/query/functions"}}');var i=a(74848),r=a(28453);const c={title:"Querying Facets"},t=void 0,l={},d=[{value:"Sample Data",id:"sample-data",level:2},{value:"Querying Facets",id:"querying-facets",level:2},{value:"Query Specific Facets",id:"query-specific-facets",level:3},{value:"Query All Facets",id:"query-all-facets",level:3},{value:"Facets on UID Predicates",id:"facets-on-uid-predicates",level:3},{value:"Using Aliases",id:"using-aliases",level:3},{value:"Filtering on Facets",id:"filtering-on-facets",level:2},{value:"Basic Filter",id:"basic-filter",level:3},{value:"Filter and Return Facets",id:"filter-and-return-facets",level:3},{value:"Compound Filters",id:"compound-filters",level:3},{value:"Sorting by Facets",id:"sorting-by-facets",level:2},{value:"Facets with Variables",id:"facets-with-variables",level:2},{value:"Assign Facets to Variables",id:"assign-facets-to-variables",level:3},{value:"Variable Propagation",id:"variable-propagation",level:3},{value:"Aggregating Facets",id:"aggregating-facets",level:2},{value:"Internationalized Facet Keys",id:"internationalized-facet-keys",level:2}];function o(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",p:"p",pre:"pre",strong:"strong",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:["This page covers how to query and filter using facets in DQL. For an introduction to what facets are and how to create them, see ",(0,i.jsx)(n.a,{href:"../dql-schema#facets-edge-attributes",children:"Facets in Schema"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"sample-data",children:"Sample Data"}),"\n",(0,i.jsx)(n.p,{children:"The examples on this page use this data:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rdf",children:'# Schema\nname: string @index(exact, term) .\nrated: [uid] @reverse @count .\n\n# Data\n_:alice <name> "Alice" .\n_:alice <dgraph.type> "Person" .\n_:alice <mobile> "040123456" (since=2006-01-02T15:04:05) .\n_:alice <car> "MA0123" (since=2006-02-02T13:01:09, first=true) .\n\n_:bob <name> "Bob" .\n_:bob <dgraph.type> "Person" .\n_:bob <car> "MA0134" (since=2006-02-02T13:01:09) .\n\n_:charlie <name> "Charlie" .\n_:charlie <dgraph.type> "Person" .\n\n_:alice <friend> _:bob (close=true, relative=false) .\n_:alice <friend> _:charlie (close=false, relative=true) .\n_:alice <friend> _:dave (close=true, relative=true) .\n\n_:movie1 <name> "Movie 1" .\n_:movie1 <dgraph.type> "Movie" .\n\n_:alice <rated> _:movie1 (rating=3) .\n_:bob <rated> _:movie1 (rating=5) .\n_:charlie <rated> _:movie1 (rating=2) .\n'})}),"\n",(0,i.jsx)(n.h2,{id:"querying-facets",children:"Querying Facets"}),"\n",(0,i.jsx)(n.h3,{id:"query-specific-facets",children:"Query Specific Facets"}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"@facets(facet-name)"})," to retrieve specific facet values:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n name\n mobile @facets(since)\n car @facets(since)\n }\n}\n'})}),"\n",(0,i.jsxs)(n.p,{children:["Facets appear in the response at the same level as the edge, with keys like ",(0,i.jsx)(n.code,{children:"edge|facet"}),"."]}),"\n",(0,i.jsx)(n.h3,{id:"query-all-facets",children:"Query All Facets"}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"@facets"})," without arguments to retrieve all facets on an edge:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n name\n mobile @facets\n car @facets\n }\n}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"facets-on-uid-predicates",children:"Facets on UID Predicates"}),"\n",(0,i.jsx)(n.p,{children:"For relationship edges, facets appear with the child node:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n name\n friend @facets(close) {\n name\n }\n }\n}\n'})}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"close"})," facet appears with key ",(0,i.jsx)(n.code,{children:"friend|close"})," alongside each friend's data."]}),"\n",(0,i.jsx)(n.h3,{id:"using-aliases",children:"Using Aliases"}),"\n",(0,i.jsx)(n.p,{children:"Assign custom names to facet results:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n name\n car @facets(car_since: since)\n friend @facets(close_friend: close) {\n name\n }\n }\n}\n'})}),"\n",(0,i.jsx)(n.admonition,{type:"note",children:(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"orderasc"})," and ",(0,i.jsx)(n.code,{children:"orderdesc"})," are reserved and cannot be used as aliases."]})}),"\n",(0,i.jsx)(n.h2,{id:"filtering-on-facets",children:"Filtering on Facets"}),"\n",(0,i.jsxs)(n.p,{children:["Filter edges based on facet values using ",(0,i.jsx)(n.code,{children:"@facets(condition)"}),":"]}),"\n",(0,i.jsx)(n.h3,{id:"basic-filter",children:"Basic Filter"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n friend @facets(eq(close, true)) {\n name\n }\n }\n}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"filter-and-return-facets",children:"Filter and Return Facets"}),"\n",(0,i.jsx)(n.p,{children:"Combine filtering with facet retrieval:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n friend @facets(eq(close, true)) @facets(relative) {\n name\n }\n }\n}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"compound-filters",children:"Compound Filters"}),"\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"AND"}),", ",(0,i.jsx)(n.code,{children:"OR"}),", and ",(0,i.jsx)(n.code,{children:"NOT"})," to combine conditions:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n friend @facets(eq(close, true) AND eq(relative, true)) {\n name\n }\n }\n}\n'})}),"\n",(0,i.jsx)(n.h2,{id:"sorting-by-facets",children:"Sorting by Facets"}),"\n",(0,i.jsx)(n.p,{children:"Sort results by facet values on UID edges:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n me(func: anyofterms(name, "Alice Bob Charlie")) {\n name\n rated @facets(orderdesc: rating) {\n name\n }\n }\n}\n'})}),"\n",(0,i.jsx)(n.h2,{id:"facets-with-variables",children:"Facets with Variables"}),"\n",(0,i.jsx)(n.h3,{id:"assign-facets-to-variables",children:"Assign Facets to Variables"}),"\n",(0,i.jsx)(n.p,{children:"Store facet values in variables for use elsewhere in the query:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n var(func: eq(name, "Alice")) {\n friend @facets(a as close, b as relative)\n }\n\n close_friends(func: uid(a)) {\n name\n val(a)\n }\n\n relatives(func: uid(b)) {\n name\n val(b)\n }\n}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"variable-propagation",children:"Variable Propagation"}),"\n",(0,i.jsxs)(n.p,{children:["Numeric facets (",(0,i.jsx)(n.code,{children:"int"}),", ",(0,i.jsx)(n.code,{children:"float"}),") propagate through queries. When multiple paths reach the same node, values are summed:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n var(func: anyofterms(name, "Alice Bob Charlie")) {\n num_raters as math(1)\n rated @facets(r as rating) {\n total_rating as math(r)\n average_rating as math(total_rating / num_raters)\n }\n }\n \n data(func: uid(total_rating)) {\n name\n val(total_rating)\n val(average_rating)\n }\n}\n'})}),"\n",(0,i.jsx)(n.h2,{id:"aggregating-facets",children:"Aggregating Facets"}),"\n",(0,i.jsx)(n.p,{children:"Facet values in variables can be aggregated:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'{\n data(func: eq(name, "Alice")) {\n name\n rated @facets(r as rating) {\n name\n }\n avg(val(r))\n }\n}\n'})}),"\n",(0,i.jsxs)(n.admonition,{type:"warning",children:[(0,i.jsx)(n.p,{children:"When a query reaches nodes through multiple paths, facet values are summed. This affects aggregations:"}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:'# This does NOT calculate individual averages correctly\n{\n data(func: anyofterms(name, "Alice Bob")) {\n name\n rated @facets(r as rating) {\n name\n }\n avg(val(r)) # Incorrect: r contains summed values\n }\n}\n'})}),(0,i.jsx)(n.p,{children:"Calculate per-user averages with separate variable mappings:"}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:"{\n var(func: has(rated)) {\n num_rated as math(1)\n rated @facets(r as rating) {\n avg_rating as math(r / num_rated)\n }\n }\n\n data(func: uid(avg_rating)) {\n name\n val(avg_rating)\n }\n}\n"})})]}),"\n",(0,i.jsx)(n.h2,{id:"internationalized-facet-keys",children:"Internationalized Facet Keys"}),"\n",(0,i.jsx)(n.p,{children:"Facet keys can use language-specific characters. When querying, enclose them in angle brackets:"}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Mutation:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-rdf",children:'_:person1 <name> "Daniel" (\u0935\u0902\u0936="\u0938\u094d\u092a\u0947\u0928\u0940", ancestry="Espa\xf1ol") .\n'})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Query:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-dql",children:"{\n q(func: has(name)) {\
1n name @facets(<\u0935\u0902\u0936>)\n }\n}\n"})}),"\n",(0,i.jsxs)(n.p,{children:["See ",(0,i.jsx)(n.a,{href:"../dql-schema#predicates-i18n",children:"Predicates i18n"})," for more on internationalization."]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(o,{...e})}):o(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.