docs(filter): add filter query explanation
This commit is contained in:
parent
e0a7f46e5d
commit
d0b762d761
GPG Key ID:
F40E70337AB24C9B
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
title: "Filters"
|
||||
date: 2024-03-09T19:51:32+02:00
|
||||
draft: false
|
||||
type: doc
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
---
|
||||
|
||||
# Filter Syntax
|
||||
|
||||
To filter tasks via the api, you can use a query syntax similar to SQL.
|
||||
|
||||
This document is about filtering via the api. To filter in Vikunja's web ui, check out the help text below the filter query input.
|
||||
|
||||
{{< table_of_contents >}}
|
||||
|
||||
## Available fields
|
||||
|
||||
The available fields for filtering include:
|
||||
|
||||
* `done`: Whether the task is completed or not
|
||||
* `priority`: The priority level of the task (1-5)
|
||||
* `percentDone`: The percentage of completion for the task (0-100)
|
||||
* `dueDate`: The due date of the task
|
||||
* `startDate`: The start date of the task
|
||||
* `endDate`: The end date of the task
|
||||
* `doneAt`: The date and time when the task was completed
|
||||
* `assignees`: The assignees of the task
|
||||
* `labels`: The labels associated with the task
|
||||
* `project`: The project the task belongs to (only available for saved filters, not on a project level)
|
||||
|
||||
You can date math to set relative dates. Click on the date value in a query to find out more.
|
||||
|
||||
## Operators
|
||||
|
||||
The available operators for filtering include:
|
||||
|
||||
* `!=`: Not equal to
|
||||
* `=`: Equal to
|
||||
* `>`: Greater than
|
||||
* `>=`: Greater than or equal to
|
||||
* `<`: Less than
|
||||
* `<=`: Less than or equal to
|
||||
* `like`: Matches a pattern (using wildcard `%`)
|
||||
* `in`: Matches any value in a list
|
||||
|
||||
To combine multiple conditions, you can use the following logical operators:
|
||||
|
||||
* `&&`: AND operator, matches if all conditions are true
|
||||
* `||`: OR operator, matches if any of the conditions are true
|
||||
* `(` and `)`: Parentheses for grouping conditions
|
||||
|
||||
## Examples
|
||||
|
||||
Here are some examples of filter queries:
|
||||
|
||||
* `priority = 4`: Matches tasks with priority level 4
|
||||
* `dueDate < now`: Matches tasks with a due date in the past
|
||||
* `done = false && priority >= 3`: Matches undone tasks with priority level 3 or higher
|
||||
* `assignees in [user1, user2]`: Matches tasks assigned to either "user1" or "user2
|
||||
* `(priority = 1 || priority = 2) && dueDate <= now`: Matches tasks with priority level 1 or 2 and a due date in the past
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
<script setup lang="ts">
|
||||
import {ref} from 'vue'
|
||||
import BaseButton from '@/components/base/BaseButton.vue'
|
||||
|
||||
const showDocs = ref(false)
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<BaseButton @click="showDocs = !showDocs" class="has-text-primary">
|
||||
{{ $t('filters.query.help.link') }}
|
||||
</BaseButton>
|
||||
|
||||
<Transition>
|
||||
<div v-if="showDocs" class="content">
|
||||
<p>{{ $t('filters.query.help.intro') }}</p>
|
||||
<ul>
|
||||
<li><code>done</code>: {{ $t('filters.query.help.fields.done') }}</li>
|
||||
<li><code>priority</code>: {{ $t('filters.query.help.fields.priority') }}</li>
|
||||
<li><code>percentDone</code>: {{ $t('filters.query.help.fields.percentDone') }}</li>
|
||||
<li><code>dueDate</code>: {{ $t('filters.query.help.fields.dueDate') }}</li>
|
||||
<li><code>startDate</code>: {{ $t('filters.query.help.fields.startDate') }}</li>
|
||||
<li><code>endDate</code>: {{ $t('filters.query.help.fields.endDate') }}</li>
|
||||
<li><code>doneAt</code>: {{ $t('filters.query.help.fields.doneAt') }}</li>
|
||||
<li><code>assignees</code>: {{ $t('filters.query.help.fields.assignees') }}</li>
|
||||
<li><code>labels</code>: {{ $t('filters.query.help.fields.labels') }}</li>
|
||||
<li><code>project</code>: {{ $t('filters.query.help.fields.project') }}</li>
|
||||
</ul>
|
||||
<p>{{ $t('filters.query.help.canUseDatemath') }}</p>
|
||||
<p>{{ $t('filters.query.help.operators.intro') }}</p>
|
||||
<ul>
|
||||
<li><code>!=</code>: {{ $t('filters.query.help.operators.notEqual') }}</li>
|
||||
<li><code>=</code>: {{ $t('filters.query.help.operators.equal') }}</li>
|
||||
<li><code>></code>: {{ $t('filters.query.help.operators.greaterThan') }}</li>
|
||||
<li><code>>=</code>: {{ $t('filters.query.help.operators.greaterThanOrEqual') }}</li>
|
||||
<li><code><</code>: {{ $t('filters.query.help.operators.lessThan') }}</li>
|
||||
<li><code><=</code>: {{ $t('filters.query.help.operators.lessThanOrEqual') }}</li>
|
||||
<li><code>like</code>: {{ $t('filters.query.help.operators.like') }}</li>
|
||||
<li><code>in</code>: {{ $t('filters.query.help.operators.in') }}</li>
|
||||
</ul>
|
||||
<p>{{ $t('filters.query.help.logicalOperators.intro') }}</p>
|
||||
<ul>
|
||||
<li><code>&&</code>: {{ $t('filters.query.help.logicalOperators.and') }}</li>
|
||||
<li><code>||</code>: {{ $t('filters.query.help.logicalOperators.or') }}</li>
|
||||
<li><code>(</code> and <code>)</code>: {{ $t('filters.query.help.logicalOperators.parentheses') }}</li>
|
||||
</ul>
|
||||
<p>{{ $t('filters.query.help.examples.intro') }}</p>
|
||||
<ul>
|
||||
<li><code>priority = 4</code>: {{ $t('filters.query.help.examples.priorityEqual') }}</li>
|
||||
<li><code>dueDate < now</code>: {{ $t('filters.query.help.examples.dueDatePast') }}</li>
|
||||
<li><code>done = false && priority >= 3</code>:
|
||||
{{ $t('filters.query.help.examples.undoneHighPriority') }}
|
||||
</li>
|
||||
<li><code>assignees in [user1, user2]</code>: {{ $t('filters.query.help.examples.assigneesIn') }}</li>
|
||||
<li><code>(priority = 1 || priority = 2) && dueDate <= now</code>:
|
||||
{{ $t('filters.query.help.examples.priorityOneOrTwoPastDue') }}
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</Transition>
|
||||
</template>
|
||||
|
||||
<style scoped lang="scss">
|
||||
.v-enter-active,
|
||||
.v-leave-active {
|
||||
transition: all $transition-duration ease;
|
||||
}
|
||||
|
||||
.v-enter-from,
|
||||
.v-leave-to {
|
||||
transform: scaleY(0);
|
||||
}
|
||||
</style>
|
||||
|
|
@ -19,6 +19,8 @@
|
|||
</Fancycheckbox>
|
||||
</div>
|
||||
|
||||
<FilterInputDocs/>
|
||||
|
||||
<template #footer>
|
||||
<x-button
|
||||
variant="primary"
|
||||
|
|
@ -44,6 +46,7 @@ import type {TaskFilterParams} from '@/services/taskCollection'
|
|||
import {useLabelStore} from '@/stores/labels'
|
||||
import {useProjectStore} from '@/stores/projects'
|
||||
import {FILTER_OPERATORS, transformFilterStringForApi, transformFilterStringFromApi} from '@/helpers/filters'
|
||||
import FilterInputDocs from '@/components/project/partials/FilterInputDocs.vue'
|
||||
|
||||
const props = defineProps({
|
||||
hasTitle: {
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
import {snakeCase} from 'snake-case'
|
||||
import {camelCase} from 'camel-case'
|
||||
|
||||
export const DATE_FIELDS = [
|
||||
'dueDate',
|
||||
|
|
|
|||
|
|
@ -419,7 +419,49 @@
|
|||
},
|
||||
"query": {
|
||||
"title": "Query",
|
||||
"placeholder": "Type a search or filter query…"
|
||||
"placeholder": "Type a search or filter query…",
|
||||
"help": {
|
||||
"intro": "To filter tasks, you can use a query syntax similar to SQL. The available fields for filtering include:",
|
||||
"link": "How does this work?",
|
||||
"canUseDatemath": "You can date math to set relative dates. Click on the date value in a query to find out more.",
|
||||
"fields": {
|
||||
"done": "Whether the task is completed or not",
|
||||
"priority": "The priority level of the task (1-5)",
|
||||
"percentDone": "The percentage of completion for the task (0-100)",
|
||||
"dueDate": "The due date of the task",
|
||||
"startDate": "The start date of the task",
|
||||
"endDate": "The end date of the task",
|
||||
"doneAt": "The date and time when the task was completed",
|
||||
"assignees": "The assignees of the task",
|
||||
"labels": "The labels associated with the task",
|
||||
"project": "The project the task belongs to (only available for saved filters, not on a project level)"
|
||||
},
|
||||
"operators": {
|
||||
"intro": "The available operators for filtering include:",
|
||||
"notEqual": "Not equal to",
|
||||
"equal": "Equal to",
|
||||
"greaterThan": "Greater than",
|
||||
"greaterThanOrEqual": "Greater than or equal to",
|
||||
"lessThan": "Less than",
|
||||
"lessThanOrEqual": "Less than or equal to",
|
||||
"like": "Matches a pattern (using wildcard %)",
|
||||
"in": "Matches any value in a list"
|
||||
},
|
||||
"logicalOperators": {
|
||||
"intro": "To combine multiple conditions, you can use the following logical operators:",
|
||||
"and": "AND operator, matches if all conditions are true",
|
||||
"or": "OR operator, matches if any of the conditions are true",
|
||||
"parentheses": "Parentheses for grouping conditions"
|
||||
},
|
||||
"examples": {
|
||||
"intro": "Here are some examples of filter queries:",
|
||||
"priorityEqual": "Matches tasks with priority level 4",
|
||||
"dueDatePast": "Matches tasks with a due date in the past",
|
||||
"undoneHighPriority": "Matches undone tasks with priority level 3 or higher",
|
||||
"assigneesIn": "Matches tasks assigned to either \"user1\" or \"user2\"",
|
||||
"priorityOneOrTwoPastDue": "Matches tasks with priority level 1 or 2 and a due date in the past"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"migrate": {
|
||||
|
|
@ -593,19 +635,16 @@
|
|||
"date": "Date",
|
||||
"ranges": {
|
||||
"today": "Today",
|
||||
|
||||
"thisWeek": "This Week",
|
||||
"restOfThisWeek": "The Rest of This Week",
|
||||
"nextWeek": "Next Week",
|
||||
"next7Days": "Next 7 Days",
|
||||
"lastWeek": "Last Week",
|
||||
|
||||
"thisMonth": "This Month",
|
||||
"restOfThisMonth": "The Rest of This Month",
|
||||
"nextMonth": "Next Month",
|
||||
"next30Days": "Next 30 Days",
|
||||
"lastMonth": "Last Month",
|
||||
|
||||
"thisYear": "This Year",
|
||||
"restOfThisYear": "The Rest of This Year"
|
||||
},
|
||||
|
|
@ -613,7 +652,6 @@
|
|||
"now": "Now",
|
||||
"startOfToday": "Start of today",
|
||||
"endOfToday": "End of today",
|
||||
|
||||
"beginningOflastWeek": "Beginning of last week",
|
||||
"endOfLastWeek": "End of last week",
|
||||
"beginningOfThisWeek": "Beginning of this week",
|
||||
|
|
@ -621,7 +659,6 @@
|
|||
"startOfNextWeek": "Start of next week",
|
||||
"endOfNextWeek": "End of next week",
|
||||
"in7Days": "In 7 days",
|
||||
|
||||
"beginningOfLastMonth": "Beginning of last month",
|
||||
"endOfLastMonth": "End of last month",
|
||||
"startOfThisMonth": "Start of this month",
|
||||
|
|
@ -629,7 +666,6 @@
|
|||
"startOfNextMonth": "Start of next month",
|
||||
"endOfNextMonth": "End of next month",
|
||||
"in30Days": "In 30 days",
|
||||
|
||||
"startOfThisYear": "Beginning of this year",
|
||||
"endOfThisYear": "End of this year"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -121,10 +121,7 @@ func getTaskFilterOptsFromCollection(tf *TaskCollection) (opts *taskSearchOption
|
|||
// @Param s query string false "Search tasks by task text."
|
||||
// @Param sort_by query string false "The sorting parameter. You can pass this multiple times to get the tasks ordered by multiple different parametes, along with `order_by`. Possible values to sort by are `id`, `title`, `description`, `done`, `done_at`, `due_date`, `created_by_id`, `project_id`, `repeat_after`, `priority`, `start_date`, `end_date`, `hex_color`, `percent_done`, `uid`, `created`, `updated`. Default is `id`."
|
||||
// @Param order_by query string false "The ordering parameter. Possible values to order by are `asc` or `desc`. Default is `asc`."
|
||||
// @Param filter_by query string false "The name of the field to filter by. Allowed values are all task properties. Task properties which are their own object require passing in the id of that entity. Accepts an array for multiple filters which will be chanied together, all supplied filter must match."
|
||||
// @Param filter_value query string false "The value to filter for. You can use [grafana](https://grafana.com/docs/grafana/latest/dashboards/time-range-controls)- or [elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/common-options.html#date-math)-style relative dates for all date fields like `due_date`, `start_date`, `end_date`, etc."
|
||||
// @Param filter_comparator query string false "The comparator to use for a filter. Available values are `equals`, `greater`, `greater_equals`, `less`, `less_equals`, `like` and `in`. `in` expects comma-separated values in `filter_value`. Defaults to `equals`"
|
||||
// @Param filter_concat query string false "The concatinator to use for filters. Available values are `and` or `or`. Defaults to `or`."
|
||||
// @Param filter query string false "The filter query to match tasks by. Check out https://vikunja.io/docs/filters for a full explanation of the feature."
|
||||
// @Param filter_include_nulls query string false "If set to true the result will include filtered fields whose value is set to `null`. Available values are `true` or `false`. Defaults to `false`."
|
||||
// @Security JWTKeyAuth
|
||||
// @Success 200 {array} models.Task "The tasks"
|
||||
|
|
|
|||
Loading…
Reference in New Issue