queryCollection
Usage
Use the auto-imported queryCollection
to find contents inside a collection. Here we assume that you have defined docs
collection inside content.config.ts
.
If you have not defined any collection, check How to define a collection.
<script>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () => {
return queryCollection('docs').path(route.path).first()
})
</script>
queryCollection
utility is available in both Vue and Nitro. Checkout Server Usage for more details on how to use it on the server side.API
Type
function queryCollection<T extends keyof Collections>(collection: T): CollectionQueryBuilder<Collections[T]>
interface CollectionQueryBuilder<T> {
where(field: keyof T | string, operator: SQLOperator, value?: unknown): CollectionQueryBuilder<T>
andWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>
orWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>
order(field: keyof T, direction: 'ASC' | 'DESC'): CollectionQueryBuilder<T>
// ... other methods
}
queryCollection(collection: CollectionName)
Create a query builder to search in the specific collection.
- Parameters:
collection
: The key of defined collection incontent.config.ts
path(path: string)
Search for contents that have specific path
. (path
is an special field in page
collections which generates based on fs path and can be use as route to render the content)
- Parameter:
path
: The path string to match.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs').path(route.path).first()
})
select(...fields: keyof Collection)
Select specific fields from the collection to be returned in the query result.
- Parameters:
...fields
: A list of field names to select from the collection.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs')
.select('path', 'title', 'description')
.first()
})
where(field: keyof Collection | string, operator: SqlOperator, value?: unknown)
Add a condition to the query to filter results based on a specific field.
- Parameters:
field
: The field to filter onoperator
: The SQL operator to use for comparison. Possible values include:'='
: Equal to'>'
: Greater than'<'
: Less than'<>'
: Not equal to'IN'
: In a list of values'BETWEEN'
: Between two values'NOT BETWEEN'
: Not between two values'IS NULL'
: Is null'IS NOT NULL'
: Is not null'LIKE'
: Matches a pattern'NOT LIKE'
: Does not match a pattern
value
: The value to compare against. The type depends on the operator used.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs')
.where('date', '<', '2024-04-04')
.all()
})
andWhere(groupFactory: QueryGroupFunction<Collection>)
Add an AND condition group to the query. This allows for more complex query conditions.
- Parameter:
groupFactory
: A function that receives a query builder and can add multiple conditions that will be grouped together with AND
const { data } = await useAsyncData('recent-docs', () => {
return queryCollection('docs')
.where('published', '=', true)
.andWhere(query => {
query.where('date', '>', '2024-01-01')
.where('category', '=', 'news')
})
.all()
})
orWhere(groupFactory: QueryGroupFunction<Collection>)
Add an OR condition group to the query. This allows for alternative conditions.
- Parameter:
groupFactory
: A function that receives a query builder and can add multiple conditions that will be grouped together with OR
const { data } = await useAsyncData('featured-docs', () => {
return queryCollection('docs')
.where('published', '=', true)
.orWhere(query => {
query.where('featured', '=', true)
.where('priority', '>', 5)
})
.all()
})
order(field: keyof Collection, direction: 'ASC' | DESC)
Order the query results based on a specific field.
- Parameters:
field
: The field to order by.direction
: The direction of ordering, either 'ASC' for ascending or 'DESC' for descending.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs')
.order('date', 'DESC')
.all()
})
limit(limit: number)
Limit the number of results returned by the query.
- Parameter:
limit
: The maximum number of results to return.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs')
.limit(10)
.all()
})
skip(skip: number)
Skip a specified number of results in the query.
- Parameter:
skip
: The number of results to skip.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs')
// Skip first 5 items
.skip(5)
.all()
})
all()
Execute the query and return all matching results.
- Returns: A Promise that resolves to an array of all matching documents.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs').all()
})
first()
Execute the query and return the first matching result.
- Returns: A Promise that resolves to the first matching document, or
null
if no documents match.
const route = useRoute()
const { data } = await useAsyncData(route.path, () => {
return queryCollection('docs').first()
})
Examples
Here is a complete example of how to fetch list of documents in docs
collections.
<script setup lang="ts">
const { data: docs } = await useAsyncData('documents-list', () => {
return queryCollection('docs')
.order('date', 'DESC')
.select('title', 'path', 'description')
.all()
})
</script>
<template>
<NuxtLink v-for="doc in docs" :key="doc.path" :to="doc.path">
<h2>{{ doc.title }}</h2>
<p>{{ doc.description }}</p>
</NuxtLink>
</template>
Server Usage
Nuxt Content provides a similar utility to query collections on the server side. The only difference is that you need to pass event
as the first argument to the queryCollection
function.
export default eventHandler(async (event) => {
const { slug } = getRouterParams(event)
const page = await queryCollection(event, 'docs').path(slug).first()
return page
})
server/tsconfig.json
file with the following content to avoid type error.{
"extends": "../.nuxt/tsconfig.server.json"
}