# Filter Resource
A filter resource represents an instance of a filter inside MaxScale. Multiple\
services can use the same filter and a single service can use multiple filters.
* [Filter Resource](#filter-resource)
* [Resource Operations](#resource-operations)
* [Get a filter](#get-a-filter)
* [Response](#response)
* [Get all filters](#get-all-filters)
* [Response](#response_1)
* [Create a filter](#create-a-filter)
* [Response](#response_2)
* [Update a filter](#update-a-filter)
* [Response](#response_3)
* [Destroy a filter](#destroy-a-filter)
* [Response](#response_4)
### Resource Operations
The *:name* in all of the URIs must be the name of a filter in MaxScale.
#### Get a filter
Get a single filter.
```
GET /v1/filters/:name
```
**Response**
`Status: 200 OK`
```
{
"data": {
"attributes": {
"filter_diagnostics": null,
"module": "qlafilter",
"parameters": {
"append": false,
"duration_unit": "ms",
"exclude": null,
"filebase": "/tmp/qla.log",
"flush": true,
"log_data": "date,user,query",
"log_type": "unified",
"match": null,
"module": "qlafilter",
"newline_replacement": " ",
"options": "",
"separator": ",",
"source": null,
"source_exclude": null,
"source_match": null,
"use_canonical_form": false,
"user": null,
"user_exclude": null,
"user_match": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "QLA",
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/QLA/relationships/services/"
}
}
},
"type": "filters"
},
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
}
}
```
#### Get all filters
Get all filters.
```
GET /v1/filters
```
**Response**
`Status: 200 OK`
```
{
"data": [
{
"attributes": {
"module": "hintfilter",
"parameters": {
"module": "hintfilter"
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "Hint",
"links": {
"self": "http://localhost:8989/v1/filters/Hint/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/Hint/relationships/services/"
}
}
},
"type": "filters"
},
{
"attributes": {
"filter_diagnostics": null,
"module": "qlafilter",
"parameters": {
"append": false,
"duration_unit": "ms",
"exclude": null,
"filebase": "/tmp/qla.log",
"flush": true,
"log_data": "date,user,query",
"log_type": "unified",
"match": null,
"module": "qlafilter",
"newline_replacement": " ",
"options": "",
"separator": ",",
"source": null,
"source_exclude": null,
"source_match": null,
"use_canonical_form": false,
"user": null,
"user_exclude": null,
"user_match": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "QLA",
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/QLA/relationships/services/"
}
}
},
"type": "filters"
}
],
"links": {
"self": "http://localhost:8989/v1/filters/"
}
}
```
#### Create a filter
```
POST /v1/filters
```
Create a new filter. The posted object must define at\
least the following fields.
* `data.id`
* Name of the filter
* `data.type`
* Type of the object, must be `filters`
* `data.atttributes.module`
* The filter module to use
All of the filter parameters should be defined at creation time in the`data.atttributes.parameters` object.
As the service to filter relationship is ordered (filters are applied in the\
order they are listed), filter to service relationships cannot be defined at\
creation time.
The following example defines a request body which creates a new filter.
```
{
"data": {
"id": "test-filter", // Name of the filter
"type": "filters",
"attributes": {
"module": "qlafilter", // The filter uses the qlafilter module
"parameters": { // Filter parameters
"filebase": "/tmp/qla.log"
}
}
}
}
```
**Response**
Filter is created:
`Status: 204 No Content`
#### Update a filter
```
PATCH /v1/filters/:name
```
Filter parameters can be updated at runtime if the module supports it. Refer to\
the individual module documentation for more details on whether it supports\
runtime configuration and which parameters can be updated.
The following example modifies a filter by changing the `match` parameter to`.*users.*`.
```
{
"data": {
"attributes": {
"parameters": {
"match": ".*users.*"
}
}
}
}
```
**Response**
Filter is modified:
`Status: 204 No Content`
#### Destroy a filter
```
DELETE /v1/filters/:filter
```
The *:filter* in the URI must map to the name of the filter to be destroyed.
A filter can only be destroyed if no service uses it. This means that the`data.relationships` object for the filter must be empty. Note that the service\
→ filter relationship cannot be modified from the filters resource and must be\
done via the services resource.
This endpoint also supports the `force=yes` parameter that will unconditionally\
delete the filter by first removing it from all services that it uses.
**Response**
Filter is destroyed:
`Status: 204 No Content`
*This page is licensed: CC BY-SA / Gnu FDL*
{% @marketo/form formId="4316" %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://mariadb.com/docs/maxscale/maxscale-archive/archive/mariadb-maxscale-23-02/mariadb-maxscale-23-02-rest-api/mariadb-maxscale-2302-filter-resource.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.