> ## Documentation Index
> Fetch the complete documentation index at: https://brightdata-ipv6-release.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 过滤数据集

> Create a dataset snapshot based on a provided filter

<Tip>
  将您的 API 令牌粘贴到授权字段中。要获取令牌，[创建一个账户](https://brightdata.com/?hs_signup=1\&utm_source=docs\&utm_campaign=playground)，并了解如何[生成令牌](/api-reference/unlocker/api_token)。
</Tip>

## 一般描述

* 调用此端点将启动异步作业，以过滤数据集并在您的账户中创建包含过滤数据的快照。

* 该作业的最大完成时间为 5 分钟。如果在此时间范围内未完成，作业将被取消。

* 创建数据集快照的费用取决于快照大小和记录单价。

* 过滤组的最大嵌套深度为 3。

## 过滤语法

### 运算符

下表显示了可用于字段过滤的运算符。

| 操作符                  | 字段类型   | 描述                                                                                |
| -------------------- | ------ | --------------------------------------------------------------------------------- |
| =                    | 任意     | 等于                                                                                |
| !=                   | 任意     | 不等于                                                                               |
| \<                   | 数字, 日期 | 小于                                                                                |
| \<=                  | 数字, 日期 | 小于或等于                                                                             |
| >                    | 数字, 日期 | 大于                                                                                |
| >=                   | 数字, 日期 | 大于或等于                                                                             |
| `in`                 | 任意     | 测试字段值是否等于筛选值中提供的任意值                                                               |
| `not_in`             | 任意     | 测试字段值是否不等于筛选值中提供的所有值                                                              |
| `includes`           | 数组, 文本 | 测试字段值是否包含筛选值。如果筛选值是一个单一字符串，则匹配字段值包含该字符串的记录。如果筛选值是一个字符串数组，则匹配字段值包含数组中的至少一个字符串的记录。  |
| `not_includes`       | 数组, 文本 | 测试字段值是否不包含筛选值。如果筛选值是一个单一字符串，则匹配字段值不包含该字符串的记录。如果筛选值是一个字符串数组，则匹配字段值不包含数组中的任何字符串的记录。 |
| `array_includes`     | 数组     | 测试筛选值是否在字段值中（精确匹配）                                                                |
| `not_array_includes` | 数组     | 测试筛选值是否不在字段值中（精确匹配）                                                               |
| `is_null`            | 任意     | 测试字段值是否等于 NULL。操作符不接受任何值。                                                         |
| `is_not_null`        | 任意     | 测试字段值是否不等于 NULL。操作符不接受任何值。                                                        |

### 组合多个筛选器

可以使用两个逻辑运算符：'and'（与），'or'（或）将多个字段筛选器组合成筛选器组。\
API 支持最多 3 层嵌套的筛选器。\
筛选器组示例：

```json theme={null}
{
    // operator can be one of ["and", "or"]
    "operator": "and",
    // an array of field filters
    "filters": [
        {
            "name": "reviews_count",
            "opeartor": ">",
            "value": "200"
        },
        {
            "name": "rating",
            "operator": ">",
            "value": "4.5"
        }
    ]
}
```


## OpenAPI

````yaml dca-api POST /datasets/filter
openapi: 3.1.0
info:
  title: Brightdata API
  description: API for interaction with datasets marketplace
  version: 1.0.0
servers:
  - url: https://api.brightdata.com
security:
  - bearerAuth: []
paths:
  /datasets/filter:
    post:
      description: Create a dataset snapshot based on a provided filter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterDatasetBody'
      responses:
        '200':
          description: Job of creating the snapshot successfully started
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshot_id:
                    type: string
                    description: ID of the snapshot
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorBody'
                example:
                  validation_errors:
                    - '"filter.filters[0].invalid_prop" is not allowed'
                    - '"records_limit" must be a positive number'
        '402':
          description: Not enough funds to create the snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
                example:
                  error: >-
                    Your current balance is insufficient to process this data
                    collection request. Please add funds to your account or
                    adjust your request to continue. ($1 is missing)
        '422':
          description: Provided filter did not match any records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
                example:
                  error: Provided filter did not match any records
        '429':
          description: Too many parallel jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
                example:
                  error: Maximum limit of 100 jobs per dataset has been exceeded
components:
  schemas:
    FilterDatasetBody:
      required:
        - filter
        - dataset_id
      type: object
      properties:
        dataset_id:
          type: string
          description: ID of the dataset to filter
        filter:
          $ref: '#/components/schemas/DatasetFilter'
        records_limit:
          type: integer
          'description:': Limit the number of records to include in the snapshot
    ValidationErrorBody:
      type: object
      properties:
        validation_errors:
          type: array
          items:
            type: string
    ErrorBody:
      type: object
      properties:
        error:
          type: string
    DatasetFilter:
      anyOf:
        - $ref: '#/components/schemas/DatasetFilterItem'
          title: Single field filter
        - $ref: '#/components/schemas/DatasetFilterGroup'
          title: Filters group
        - $ref: '#/components/schemas/DatasetFilterItemNoVal'
          title: Single field filter w/out value
    DatasetFilterItem:
      type: object
      required:
        - name
        - operator
        - value
      additionalProperties: false
      properties:
        name:
          type: string
          description: Field name to filter by
        operator:
          type: string
          enum:
            - '='
            - '!='
            - '>'
            - <
            - '>='
            - <=
            - in
            - not_in
            - includes
            - not_includes
            - array_includes
            - not_array_includes
        value:
          description: Value to filter by
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: object
            - type: array
              items:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
      example:
        name: name
        operator: '='
        value: John
    DatasetFilterGroup:
      type: object
      required:
        - operator
        - filters
      additionalProperties: false
      properties:
        operator:
          type: string
          enum:
            - and
            - or
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DatasetFilter'
      example:
        operator: and
        filters:
          - name: name
            operator: '='
            value: John
          - name: age
            operator: '>'
            value: '30'
    DatasetFilterItemNoVal:
      type: object
      required:
        - name
        - operator
      additionalProperties: false
      properties:
        name:
          type: string
          description: Field name to filter by
        operator:
          type: string
          enum:
            - is_null
            - is_not_null
      example:
        name: reviews_count
        operator: is_not_null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````