0
# Content Querying
1

2
Powerful query system with fluent API for filtering, sorting, and retrieving content from collections. Built on SQLite for performance with full TypeScript support and chainable methods.
3

4
## Capabilities
5

6
### Query Collection
7

8
Creates a chainable query builder for content collections with type-safe operations.
9

10
```typescript { .api }
11
/**
12
 * Creates a chainable query builder for the specified collection
13
 * @param collection - The collection name to query
14
 * @returns CollectionQueryBuilder instance for chaining operations
15
 */
16
function queryCollection<T>(collection: T): CollectionQueryBuilder<Collections[T]>;
17

18
interface CollectionQueryBuilder<T> {
19
  /** Filter by exact path match */
20
  path(path: string): CollectionQueryBuilder<T>;
21
  /** Select specific fields from the collection items */
22
  select<K>(...fields: K[]): CollectionQueryBuilder<Pick<T, K>>;
23
  /** Add WHERE condition with SQL operator */
24
  where(field: string, operator: SQLOperator, value?: unknown): CollectionQueryBuilder<T>;
25
  /** Add AND grouped conditions */
26
  andWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>;
27
  /** Add OR grouped conditions */
28
  orWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>;
29
  /** Sort results by field in ascending or descending order */
30
  order(field: keyof T, direction: 'ASC' | 'DESC'): CollectionQueryBuilder<T>;
31
  /** Limit number of results returned */
32
  limit(limit: number): CollectionQueryBuilder<T>;
33
  /** Skip the first N results (pagination) */
34
  skip(skip: number): CollectionQueryBuilder<T>;
35
  /** Execute query and return all matching results */
36
  all(): Promise<T[]>;
37
  /** Execute query and return first result or null */
38
  first(): Promise<T | null>;
39
  /** Count matching results, optionally with distinct values */
40
  count(field?: keyof T | '*', distinct?: boolean): Promise<number>;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
// Basic content retrieval
48
const article = await queryCollection('articles')
49
  .path('/blog/introduction')
50
  .first();
51

52
// Complex filtering with multiple conditions
53
const publishedPosts = await queryCollection('blog')
54
  .where('published', '=', true)
55
  .where('date', '>', '2024-01-01')
56
  .order('date', 'DESC')
57
  .limit(10)
58
  .all();
59

60
// Field selection for performance
61
const postSummaries = await queryCollection('blog')
62
  .select('title', 'slug', 'date', 'excerpt')
63
  .where('featured', '=', true)
64
  .all();
65

66
// Pagination
67
const page2Posts = await queryCollection('blog')
68
  .order('date', 'DESC')
69
  .skip(20)
70
  .limit(10)
71
  .all();
72

73
// Counting results
74
const totalPosts = await queryCollection('blog')
75
  .where('published', '=', true)
76
  .count();
77
```
78

79
### Query Navigation
80

81
Generates hierarchical navigation trees from content collections.
82

83
```typescript { .api }
84
/**
85
 * Generate navigation tree from collection
86
 * @param collection - Collection to build navigation from
87
 * @param fields - Optional specific fields to include in navigation items
88
 * @returns Promise resolving to navigation tree
89
 */
90
function queryCollectionNavigation<T>(
91
  collection: T,
92
  fields?: Array<keyof PageCollections[T]>
93
): ChainablePromise<T, ContentNavigationItem[]>;
94

95
interface ContentNavigationItem {
96
  /** Display title for navigation item */
97
  title: string;
98
  /** URL path for navigation item */
99
  path: string;
100
  /** File stem (filename without extension) */
101
  stem?: string;
102
  /** Child navigation items */
103
  children?: ContentNavigationItem[];
104
  /** Whether this is a page (true) or directory (false) */
105
  page?: boolean;
106
  /** Additional custom fields from content */
107
  [key: string]: unknown;
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
// Generate full navigation tree
115
const navigation = await queryCollectionNavigation('pages');
116

117
// Include specific fields in navigation items
118
const navWithMeta = await queryCollectionNavigation('docs', [
119
  'title', 'description', 'category', 'order'
120
]);
121
```
122

123
### Query Surroundings
124

125
Find content items before and after a given path for navigation (previous/next).
126

127
```typescript { .api }
128
/**
129
 * Find content items surrounding a given path
130
 * @param collection - Collection to search in
131
 * @param path - Current path to find surroundings for
132
 * @param options - Optional configuration for surround behavior
133
 * @returns Promise resolving to array with [previous, next] items
134
 */
135
function queryCollectionItemSurroundings<T>(
136
  collection: T,
137
  path: string,
138
  opts?: SurroundOptions
139
): ChainablePromise<T, ContentNavigationItem[]>;
140

141
interface SurroundOptions {
142
  /** Fields to include in surrounding items */
143
  fields?: string[];
144
  /** Maximum number of items to return */
145
  limit?: number;
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
// Get previous and next articles
153
const [prev, next] = await queryCollectionItemSurroundings(
154
  'blog',
155
  '/blog/current-article'
156
);
157

158
// Include specific fields
159
const surroundings = await queryCollectionItemSurroundings(
160
  'docs',
161
  '/docs/current-page',
162
  { fields: ['title', 'description', 'category'] }
163
);
164
```
165

166
### Query Search Sections
167

168
Extract searchable sections from content for building search indexes.
169

170
```typescript { .api }
171
/**
172
 * Extract searchable sections from collection content
173
 * @param collection - Collection to extract sections from
174
 * @param options - Optional configuration for section extraction
175
 * @returns Promise resolving to searchable sections
176
 */
177
function queryCollectionSearchSections(
178
  collection: keyof Collections,
179
  opts?: SearchSectionOptions
180
): ChainablePromise<keyof Collections, SearchSection[]>;
181

182
interface SearchSectionOptions {
183
  /** HTML tags to ignore when extracting text */
184
  ignoredTags?: string[];
185
}
186

187
interface SearchSection {
188
  /** Section identifier */
189
  id: string;
190
  /** Section title */
191
  title: string;
192
  /** Section content text */
193
  content: string;
194
  /** Original content path */
195
  path: string;
196
  /** Section hierarchy level */
197
  level: number;
198
}
199
```
200

201
**Usage Examples:**
202

203
```typescript
204
// Extract all searchable sections
205
const sections = await queryCollectionSearchSections('docs');
206

207
// Ignore specific HTML tags
208
const cleanSections = await queryCollectionSearchSections('blog', {
209
  ignoredTags: ['code', 'pre', 'script']
210
});
211
```
212

213
### Server-side Querying
214

215
Server-side equivalents for use in Nitro handlers and API routes.
216

217
```typescript { .api }
218
/**
219
 * Server-side collection querying with H3 event context
220
 * @param event - H3 event object from Nitro handler
221
 * @param collection - Collection to query
222
 * @returns CollectionQueryBuilder for server-side use
223
 */
224
function queryCollection<T>(
225
  event: H3Event,
226
  collection: T
227
): CollectionQueryBuilder<Collections[T]>;
228

229
/**
230
 * Server-side navigation generation
231
 */
232
function queryCollectionNavigation<T>(
233
  event: H3Event,
234
  collection: T,
235
  fields?: Array<keyof PageCollections[T]>
236
): Promise<ContentNavigationItem[]>;
237

238
/**
239
 * Server-side surround content querying
240
 */
241
function queryCollectionItemSurroundings<T>(
242
  event: H3Event,
243
  collection: T,
244
  path: string,
245
  opts?: SurroundOptions
246
): Promise<ContentNavigationItem[]>;
247

248
/**
249
 * Server-side search sections querying
250
 */
251
function queryCollectionSearchSections(
252
  event: H3Event,
253
  collection: keyof Collections,
254
  opts?: SearchSectionOptions
255
): Promise<SearchSection[]>;
256
```
257

258
## Types
259

260
```typescript { .api }
261
type SQLOperator = 
262
  | '=' | '!=' | '>' | '<' | '>=' | '<='
263
  | 'IN' | 'NOT IN' 
264
  | 'LIKE' | 'NOT LIKE'
265
  | 'IS NULL' | 'IS NOT NULL';
266

267
interface QueryGroupFunction<T> {
268
  (group: CollectionQueryGroup<T>): CollectionQueryGroup<T>;
269
}
270

271
interface CollectionQueryGroup<T> {
272
  where(field: string, operator: SQLOperator, value?: unknown): CollectionQueryGroup<T>;
273
  andWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryGroup<T>;
274
  orWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryGroup<T>;
275
}
276

277
interface ChainablePromise<T, R> extends Promise<R> {
278
  collection: T;
279
}
280
```