Document the `meta` query parameter

Open Beginner friendly
#772 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
74/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
graphql, typescript
Domain
documentation

Research direction

Start with content/guides/04.connect/3.query-parameters.md and follow the existing query-parameter section format. Read sanitizeMeta in api/src/utils/sanitize-query.ts and MetaService.getMetaForQuery in api/src/services/meta.ts, then document the REST and SDK forms, explain the supported values, and note the GraphQL alternative. Update the frontmatter description to include all documented parameters, including meta.

Written by the indexing model from the issue text.

Description

Background

content/guides/04.connect/3.query-parameters.md documents every other query parameter (fields, filter, search, sort, limit, offset, page, aggregate, groupBy, deep, alias, export, version, versionRaw, functions, backlink) with its own ## section, but meta has no section and isn't mentioned anywhere on the page or elsewhere in this repo.

meta was previously proposed for deprecation in favor of aggregation (directus/directus#15665), but that was closed as not planned in 2024 ("Not dropping it, it's too popular!"). It remains fully supported today.

Scope

Add a ## Meta section to content/guides/04.connect/3.query-parameters.md, following the existing section format (description, ::code-group with REST/GraphQL/SDK tabs where applicable, any relevant ::callout).

Content notes

Source: api/src/utils/sanitize-query.ts (sanitizeMeta), api/src/services/meta.ts (MetaService.getMetaForQuery) in directus/directus.

  • Accepts total_count, filter_count, a comma-separated combination of the two, or * for both.
  • total_count: total number of items in the collection, ignoring any filters.
  • filter_count: number of items matching the current filter/search.
  • No GraphQL equivalent: GraphQL exposes counts through the separate <collection>_aggregated query type instead of a meta argument, so this section likely only needs REST + SDK tabs.

Also noticed

The page's frontmatter description field lists fields, filter, search, sort, limit, offset, page, aggregate, groupBy, deep, alias, and export - missing version, versionRaw, functions, and backlink (which already have sections), as well as meta. Worth updating in the same PR since it's the same file.

Dominant language
TypeScript
Stars
22
Forks
82
Avg merge
18h 49m
Merged PRs (30d)
4

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from directus/docs

All issues in directus/docs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.