diff --git a/raw/queries__sort.md b/raw/_processed/queries__sort.md similarity index 100% rename from raw/queries__sort.md rename to raw/_processed/queries__sort.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 92369eb..f07cc50 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 | | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | -| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 128 | +| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization, hierarchy | 129 | | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 | | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index fb51c43..c0f46ee 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -129,3 +129,4 @@ | [[wiki/payloadcms/queries-depth\|Queries — Depth (Relationship Population)]] | depth=0 (IDs only) vs depth=N (full objects), defaultDepth config, field-level maxDepth cap, performance notes, GraphQL exception | raw/queries__depth.md | 2026-05-15 | | [[wiki/payloadcms/queries-pagination\|Queries — Pagination]] | Default pagination (limit/page/pagination options), response shape (docs + metadata), limit:1 perf tip, disabling pagination for bulk ops | raw/queries__pagination.md | 2026-05-15 | | [[wiki/payloadcms/queries-select\|Queries — Select & Populate]] | Include/exclude field selection at DB level, entity-level `select` function for hooks/access, `defaultPopulate` for relationship optimization, `populate` override | raw/queries__select.md | 2026-05-15 | +| [[wiki/payloadcms/queries-sort\|Queries — Sort]] | Sort by any stored top-level field: `-field` descending, array (Local API) or comma-separated string (REST/GraphQL), index tip | raw/queries__sort.md | 2026-05-15 | diff --git a/wiki/payloadcms/queries-sort.md b/wiki/payloadcms/queries-sort.md new file mode 100644 index 0000000..3308f58 --- /dev/null +++ b/wiki/payloadcms/queries-sort.md @@ -0,0 +1,98 @@ +--- +title: "Queries — Sort" +aliases: [payload-sort, payload-query-sort] +tags: [payloadcms, queries, sort, api] +sources: [raw/queries__sort.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +## Overview + +Documents can be sorted by any **top-level stored field**. Prefix with `-` for descending order; no prefix = ascending. + +> **Constraint:** Virtual fields cannot be used for sorting unless [[wiki/payloadcms/fields-relationship|linked with a relationship field]]. The field must exist in the database. + +> **Performance:** Enable `index: true` on fields you sort by. See [[wiki/payloadcms/database-indexes|Database Indexes]]. + +--- + +## Local API + +```ts +// Single field — ascending +const posts = await payload.find({ + collection: 'posts', + sort: '-createdAt', // descending +}) + +// Multiple fields +const posts = await payload.find({ + collection: 'posts', + sort: ['priority', '-createdAt'], // array of strings +}) +``` + +--- + +## REST API + +``` +GET /api/posts?sort=-createdAt +GET /api/posts?sort=priority,-createdAt // comma-separated +``` + +Using `qs-esm` query string builder (array form): + +```ts +import { stringify } from 'qs-esm' + +const query = stringify({ sort: ['priority', '-createdAt'] }, { addQueryPrefix: true }) +fetch(`/api/posts${query}`) +``` + +--- + +## GraphQL API + +```graphql +# Single field +query { + Posts(sort: "-createdAt") { + docs { color } + } +} + +# Multiple fields — comma-separated string +query { + Posts(sort: "priority,-createdAt") { + docs { color } + } +} +``` + +--- + +## Syntax Summary + +| Context | Multiple fields | Descending prefix | +|---------|----------------|-------------------| +| Local API | Array of strings | `-fieldName` | +| REST API | Comma-separated string or array | `-fieldName` | +| GraphQL | Comma-separated string | `-fieldName` | + +--- + +## Key Takeaways + +- `-fieldName` = descending; `fieldName` = ascending — works across all three APIs +- Local API accepts an **array**; REST/GraphQL accept a **comma-separated string** (REST also accepts array via qs) +- Only **stored fields** are sortable — virtual fields require a relationship link to be sortable +- Add `index: true` to sort fields for query performance; compound sorts benefit from compound indexes (see [[wiki/payloadcms/database-indexes|Database Indexes]]) +- Sort is complementary to [[wiki/payloadcms/queries-pagination|pagination]] and [[wiki/payloadcms/queries-select|select/populate]] + +--- + +## Sources + +- `raw/queries__sort.md` — https://payloadcms.com/docs/queries/sort