注意 当サイトは、Typst v0.12.0 公式ドキュメントを、日本語コミュニティが非公式に翻訳したものです。誤訳・未訳・古い情報が含まれている可能性があるため、公式ドキュメント との併用を推奨します。このサイトの内容に誤りを発見された方は、GitHubリポジトリまでご報告を頂けましたら幸いです。我々のコミュニティにご興味のある方は、ぜひ非公式Discordサーバー「くみはんクラブ」にご参加ください。
Warning: This site provides an unofficial translation of the Typst v0.12.0 documentation by the Japanese Community. Please note that there may be some inaccuracies, untranslated sections or outdated information. We highly recommend referring to the latest official documentation as well. If you find any errors in the content, please let us know through our GitHub repository. If you are interested in our community, feel free to join our unofficial Discord server, “Kumihan Club.”
Typst ドキュメント日本語版

query

Finds elements in the document.

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

Finding elements

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

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

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

#set page(numbering: "1")

#heading(outlined: false)[
  Table of Contents
]
#context {
  let chapters = query(
    heading.where(
      level: 1,
      outlined: true,
    )
  )
  for chapter in chapters {
    let loc = chapter.location()
    let nr = numbering(
      loc.page-numbering(),
      ..counter(page).at(loc),
    )
    [#chapter.body #h(1fr) #nr \ ]
  }
}

= Introduction
#lorem(10)
#pagebreak()

== Sub-Heading
#lorem(8)

= Discussion
#lorem(18)
Preview

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

A word of caution

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

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

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

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

Command line queries

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

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

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

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

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

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

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

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

Parameters
Parameters are the inputs to a function. They are specified in parentheses after the function name.

target
label selector location function
RequiredPositional
Positional parameters are specified in order, without names.

Can be

Only locatable element functions are supported.

location
none location
Positional
Positional parameters are specified in order, without names.

Compatibility: This argument is deprecated. It only exists for compatibility with Typst 0.10 and lower and shouldn't be used anymore.

Default:none