Filters

Create and manage saved filters for datasets with complex criteria and user/team ownership.

GET /api/datasets/{datasetId}/filters

Get all saved filters for a dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug

Response:

{
  "_links": {
    "self": { "href": "/api/datasets/{datasetId}/filters" }
  },
  "_embedded": {
    "inf:filter": [
      {
        "id": "filter-high-value",
        "name": "High Value Orders",
        "description": "Orders over $10,000",
        "datasetId": "sales-2024",
        "ownerId": "user:admin",
        "criteria": {
          "amount": { "$gte": 10000 }
        },
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z",
        "permissions": {
          "edit": true,
          "delete": true
        }
      },
      {
        "id": "filter-west-region",
        "name": "West Region",
        "description": "All orders from West region",
        "datasetId": "sales-2024",
        "ownerId": "team:sales",
        "criteria": {
          "region": "West"
        },
        "createdAt": "2024-01-20T14:30:00Z",
        "updatedAt": "2024-01-20T14:30:00Z",
        "permissions": {
          "edit": true,
          "delete": false
        }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Filter Properties:

Property	Type	Description
id	string	Filter identifier
name	string	Filter display name
description	string	Filter description
datasetId	string	Parent dataset ID
ownerId	string	Owner (user or team)
criteria	object	Filter criteria object
permissions	object	User's permissions on this filter

---

POST /api/datasets/{datasetId}/filters

Create a new saved filter.

Authentication: Required

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug

Request Body:

Field	Type	Required	Description
name	string	Yes	Filter display name
description	string	No	Filter description
criteria	object	Yes	Filter criteria
ownerId	string	No	Owner ID (defaults to current user)

Example Request:

{
  "name": "Q1 High Priority Orders",
  "description": "High value orders from Q1 2024",
  "criteria": {
    "$and": [
      { "amount": { "$gte": 5000 } },
      { "order_date": { "$gte": "2024-01-01", "$lt": "2024-04-01" } },
      { "priority": "High" }
    ]
  }
}

Response:

Returns the created filter object.

Default Behavior:

• ownerId defaults to current user if not specified
• Filter is private to owner by default
• Can be shared via dataset field restrictions

---

GET /api/datasets/{datasetId}/filters/{id}

Get a single saved filter.

Authentication: Required

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Filter ID

Response:

{
  "id": "filter-high-value",
  "name": "High Value Orders",
  "description": "Orders over $10,000",
  "datasetId": "sales-2024",
  "ownerId": "user:admin",
  "owner": {
    "id": "user:admin",
    "name": "Admin User",
    "type": "user"
  },
  "criteria": {
    "amount": { "$gte": 10000 }
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "permissions": {
    "edit": true,
    "delete": true
  }
}

---

PUT /api/datasets/{datasetId}/filters/{id}

Update a saved filter.

Authentication: Required

Permission: filter:edit

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Filter ID

Request Body:

Field	Type	Description
name	string	Filter display name
description	string	Filter description
criteria	object	Filter criteria

Example Request:

{
  "name": "Updated High Value Orders",
  "description": "Orders over $15,000 (updated threshold)",
  "criteria": {
    "amount": { "$gte": 15000 }
  }
}

Response:

Returns the updated filter object.

Ownership

You cannot change the ownerId via PUT. Use the owner endpoint to transfer ownership.

---

DELETE /api/datasets/{datasetId}/filters/{id}

Delete a saved filter.

Authentication: Required

Permission: filter:edit

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Filter ID

Response:

204 No Content

Filter Usage

Filters may be referenced in reports, shares, and user preferences. Deleting a filter may affect existing configurations.

---

GET /api/datasets/{datasetId}/filters/{id}/owner

Get the filter owner principal (user or team).

Authentication: Required

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Filter ID

Response:

{
  "id": "user:admin",
  "name": "Admin User",
  "type": "user",
  "email": "admin@example.com"
}

Or for team-owned filter:

{
  "id": "team:sales",
  "name": "Sales Team",
  "type": "team",
  "description": "Sales team members"
}

---

PUT /api/datasets/{datasetId}/filters/{id}/owner

Change the filter owner.

Authentication: Required

Permission: filter:edit

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Filter ID

Request Body:

Field	Type	Required	Description
ownerId	string	Yes	New owner ID (user or team)

Example Request:

{
  "ownerId": "team:marketing"
}

Response:

{
  "id": "filter-high-value",
  "name": "High Value Orders",
  "ownerId": "team:marketing",
  "owner": {
    "id": "team:marketing",
    "name": "Marketing Team",
    "type": "team"
  }
}

---

GET /api/dataset-filters

Get all saved filters across multiple datasets.

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
datasets	array	No	Array of dataset IDs to filter by

Example Request:

GET /api/dataset-filters?datasets=["sales-2024","orders-2024"]

Response:

{
  "_links": {
    "self": { "href": "/api/dataset-filters" }
  },
  "_embedded": {
    "inf:filter": [
      {
        "id": "filter-high-value",
        "name": "High Value Orders",
        "datasetId": "sales-2024",
        "dataset": {
          "id": "sales-2024",
          "name": "Sales Data 2024"
        },
        "ownerId": "user:admin",
        "criteria": { "amount": { "$gte": 10000 } }
      },
      {
        "id": "filter-pending",
        "name": "Pending Orders",
        "datasetId": "orders-2024",
        "dataset": {
          "id": "orders-2024",
          "name": "Orders 2024"
        },
        "ownerId": "team:operations",
        "criteria": { "status": "pending" }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Use Case:

Build cross-dataset filter UIs or dashboards showing all available filters for multiple datasets.

---

POST /api/dataset-field-report-access

Set whether dataset fields can be restricted in reports (field-level security).

Authentication: Required

Permission: dataset:share

Request Body:

Object keyed by dataset ID with boolean values.

Example Request:

{
  "sales-2024": true,
  "orders-2024": false,
  "customers": true
}

Response:

{
  "updated": 3,
  "datasets": {
    "sales-2024": true,
    "orders-2024": false,
    "customers": true
  }
}

Behavior:

• true - Enable field restrictions in shares/reports
• false - Disable field restrictions (all fields visible)

Use Case:

Control whether users can create shares with field-level restrictions. When enabled, shares can specify which fields are visible to specific users/teams.

---

Filter Criteria Syntax

Filters use MongoDB-style query operators:

Comparison Operators

{
  "amount": { "$gte": 1000 }           // Greater than or equal
  "amount": { "$gt": 1000 }            // Greater than
  "amount": { "$lte": 5000 }           // Less than or equal
  "amount": { "$lt": 5000 }            // Less than
  "status": { "$eq": "completed" }      // Equal
  "status": { "$ne": "cancelled" }      // Not equal
}

Logical Operators

{
  "$and": [
    { "amount": { "$gte": 1000 } },
    { "region": "West" }
  ]
}

{
  "$or": [
    { "status": "completed" },
    { "status": "shipped" }
  ]
}

{
  "$not": {
    "region": "East"
  }
}

Array Operators

{
  "tags": { "$in": ["urgent", "priority"] }      // In array
  "category": { "$nin": ["archived", "deleted"] } // Not in array
}

String Operators

{
  "customer_name": { "$regex": "^Acme", "$options": "i" }  // Regex match
}

Existence Operators

{
  "discount": { "$exists": true }    // Field exists
  "notes": { "$exists": false }      // Field does not exist
}

Complex Example

{
  "$and": [
    {
      "$or": [
        { "region": "West" },
        { "region": "North" }
      ]
    },
    {
      "amount": { "$gte": 1000, "$lte": 10000 }
    },
    {
      "order_date": {
        "$gte": "2024-01-01",
        "$lt": "2024-04-01"
      }
    },
    {
      "status": { "$in": ["completed", "shipped"] }
    },
    {
      "customer_type": { "$ne": "internal" }
    }
  ]
}

---

Filter Usage Examples

Apply Filter to Data Query

// By filter ID
const data = await GET('/api/datasets/sales-2024/data?filter=filter-high-value&limit=100');

// By inline criteria
const criteria = encodeURIComponent(JSON.stringify({ amount: { $gte: 10000 } }));
const data = await GET(`/api/datasets/sales-2024/data?filter=${criteria}&limit=100`);

Use in Reports

Filters can be attached to reports to restrict visible data:

{
  "reportId": "monthly-sales",
  "datasetId": "sales-2024",
  "filterId": "filter-west-region"
}

Share with Filter

Apply filter when sharing dataset:

{
  "principalId": "team:marketing",
  "accessLevel": 2,
  "datasetFilterId": "filter-high-value"
}

---

Best Practices

Filter Naming

• Be descriptive: "High Value Orders > $10k" vs "Filter 1"
• Include criteria: "Q1 2024 West Region"
• Indicate owner: "(Team) Monthly Report Filter"

Filter Organization

• Create shared filters for common criteria (team-owned)
• Keep personal filters for ad-hoc analysis (user-owned)
• Document complex filters in description
• Use consistent naming conventions across team

Performance

• Index filtered fields for better query performance
• Test complex filters on sample data first
• Avoid regex when exact match suffices
• Combine filters carefully to avoid over-restriction

Security

• Validate criteria before saving
• Restrict ownership changes
• Audit filter usage in shares and reports
• Review permissions on team-owned filters

Filter Reusability

Create team-owned filters for common business rules (regions, status values, date ranges) to ensure consistency across reports and shares.