{"route":"/en-US-v0.14.1/reference/introspection/query/","title":"Query","description":"Documentation for the `query` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"finding-elements","name":"Finding elements","children":[]},{"id":"caution","name":"Caution","children":[]},{"id":"command-line-queries","name":"Command line queries","children":[{"id":"retrieving-a-specific-field","name":"Retrieving a specific field","children":[]},{"id":"querying-for-a-specific-export-target","name":"Querying for a specific export target","children":[]}]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-target","name":"target","children":[]}]}],"body":{"kind":"func","content":{"path":[],"name":"query","title":"Query","keywords":[],"oneliner":"Finds elements in the document.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Finds elements in the document.

\n

The query function lets you search your document for elements of a\nparticular type or with a particular label. To use it, you first need to\nensure that context is available.

\n

Finding elements

\n

In the example below, we manually create a table of contents instead of\nusing the outline function.

\n

To do this, we first query for all headings in the document at level 1 and\nwhere outlined is true. Querying only for headings at level 1 ensures\nthat, for the purpose of this example, sub-headings are not included in the\ntable of contents. The outlined field is used to exclude the "Table of\nContents" heading itself.

\n

Note that we open a context to be able to use the query function.

\n
#set page(numbering: "1")\n\n#heading(outlined: false)[\n  Table of Contents\n]\n#context {\n  let chapters = query(\n    heading.where(\n      level: 1,\n      outlined: true,\n    )\n  )\n  for chapter in chapters {\n    let loc = chapter.location()\n    let nr = numbering(\n      loc.page-numbering(),\n      ..counter(page).at(loc),\n    )\n    [#chapter.body #h(1fr) #nr \\ ]\n  }\n}\n\n= Introduction\n#lorem(10)\n#pagebreak()\n\n== Sub-Heading\n#lorem(8)\n\n= Discussion\n#lorem(18)\n
\"Preview\"Preview
\n

To get the page numbers, we first get the location of the elements returned\nby query with location. We then also retrieve the\npage numbering and page\ncounter at that location and apply the numbering to\nthe counter.

\n

A word of caution

\n

To resolve all your queries, Typst evaluates and layouts parts of the\ndocument multiple times. However, there is no guarantee that your queries\ncan actually be completely resolved. If you aren't careful a query can\naffect itself—leading to a result that never stabilizes.

\n

In the example below, we query for all headings in the document. We then\ngenerate as many headings. In the beginning, there's just one heading,\ntitled Real. Thus, count is 1 and one Fake heading is generated.\nTypst sees that the query's result has changed and processes it again. This\ntime, count is 2 and two Fake headings are generated. This goes on and\non. As we can see, the output has a finite amount of headings. This is\nbecause Typst simply gives up after a few attempts.

\n

In general, you should try not to write queries that affect themselves. The\nsame words of caution also apply to other introspection features like\ncounters and state.

\n
= Real\n#context {\n  let elems = query(heading)\n  let count = elems.len()\n  count * [= Fake]\n}\n
\"Preview\"
\n

Command line queries

\n

You can also perform queries from the command line with the typst query\ncommand. This command executes an arbitrary query on the document and\nreturns the resulting elements in serialized form. Consider the following\nexample.typ file which contains some invisible metadata:

\n
#metadata("This is a note") <note>\n
\n

You can execute a query on it as follows using Typst's CLI:

\n
\n$ typst query example.typ "<note>"\n[\n  {\n    "func": "metadata",\n    "value": "This is a note",\n    "label": "<note>"\n  }\n]\n
\n

Retrieving a specific field

\n

Frequently, you're interested in only one specific field of the resulting\nelements. In the case of the metadata element, the value field is the\ninteresting one. You can extract just this field with the --field\nargument.

\n
\n$ typst query example.typ "<note>" --field value\n["This is a note"]\n
\n

If you are interested in just a single element, you can use the --one\nflag to extract just it.

\n
\n$ typst query example.typ "<note>" --field value --one\n"This is a note"\n
\n

Querying for a specific export target

\n

In case you need to query a document when exporting for a specific target,\nyou can use the --target argument. Valid values are paged, and html\n(if the html feature is enabled).

"}],"self":false,"params":[{"name":"target","details":[{"kind":"html","content":"

Can be

\n\n

Only locatable element functions are supported.

"}],"types":["label","selector","location","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["array"],"scope":[]}}}