# Query Data
**Action ID:** `query_data`
## Description
Query, filter, and sort rows in a dataset with advanced filtering capabilities.
## Input Parameters
| Name | Type | Required | Default | Description |
| ---------------- | --------------------- | :------: | ------- | --------------------------------------------------------------------- |
| dataset | dropdown | ✓ | - | The dataset to query. |
| conditions | array | - | \[] | List of filter conditions (empty = return all rows). |
| logic | dropdown | - | and | How to combine conditions (AND/OR). Options: and, or |
| select\_columns | multi-select dropdown | - | \[] | Columns to return in results (empty = return all columns). |
| sort\_by\_column | dropdown | - | null | Column to sort results by (must be in selected columns if specified). |
| sort\_order | dropdown | - | asc | Ascending or descending order. Options: asc, desc |
| limit | integer | - | 100 | Maximum number of rows to return (1-1000). |
### Filter Condition Structure
Each condition in the `conditions` array contains:
| Field | Type | Description |
| -------- | -------- | ----------------------------------------------------------------------------------------- |
| column | string | Column name to filter by |
| operator | dropdown | Comparison operator: equals, not\_equals, contains, greater\_than, less\_than, in |
| value | string | Value to compare against. For 'in' operator, provide comma-separated values or JSON array |
View JSON Schema
```json
{
"description": "Query Data node input.",
"properties": {
"dataset": {
"description": "The dataset to query.",
"title": "Dataset",
"type": "string"
},
"conditions": {
"default": [],
"description": "List of filter conditions (empty = return all rows).",
"items": {
"properties": {
"column": {
"description": "Column name to filter by",
"title": "Column",
"type": "string"
},
"operator": {
"default": "equals",
"description": "Comparison operator",
"enum": ["equals", "not_equals", "contains", "greater_than", "less_than", "in"],
"title": "Operator",
"type": "string"
},
"value": {
"description": "Value to compare against. For 'in' operator, provide comma-separated values or JSON array",
"title": "Value",
"type": "string"
}
},
"required": ["column", "value"],
"type": "object"
},
"title": "Query Conditions",
"type": "array"
},
"logic": {
"default": "and",
"description": "How to combine conditions (AND/OR).",
"enum": ["and", "or"],
"title": "Logic Operator",
"type": "string"
},
"select_columns": {
"default": [],
"description": "Columns to return in results (empty = return all columns).",
"items": {
"type": "string"
},
"title": "Select Columns",
"type": "array"
},
"sort_by_column": {
"default": null,
"description": "Column to sort results by (must be in selected columns if specified).",
"title": "Sort By Column",
"type": ["string", "null"]
},
"sort_order": {
"default": "asc",
"description": "Ascending or descending order.",
"enum": ["asc", "desc"],
"title": "Sort Order",
"type": "string"
},
"limit": {
"default": 100,
"description": "Maximum number of rows to return.",
"minimum": 1,
"maximum": 1000,
"title": "Limit",
"type": "integer"
}
},
"required": ["dataset"],
"title": "QueryDataNodeInput",
"type": "object"
}
```
## Output Parameters
| Name | Type | Description |
| ----- | ------- | --------------------------------------------- |
| rows | array | The rows that match the query criteria. |
| total | integer | Total number of matching rows (before limit). |
View JSON Schema
```json
{
"description": "Query Data node output.",
"properties": {
"rows": {
"description": "The rows that match the query criteria.",
"items": {
"type": "object"
},
"title": "Rows",
"type": "array"
},
"total": {
"description": "Total number of matching rows (before limit).",
"title": "Total",
"type": "integer"
}
},
"required": ["rows", "total"],
"title": "QueryDataNodeOutput",
"type": "object"
}
```
## How It Works
This node performs advanced filtering and querying on dataset rows. It applies filter conditions using the specified logic operator (AND/OR), supports multiple comparison operators, allows column selection for optimized data retrieval, and provides sorting capabilities. The node returns both the filtered rows and the total count of matching records, enabling pagination and result analysis.
## Usage Examples
### Example 1: Query All Rows
**Input:**
```
dataset: "01K8ZM9T72FNBZAGA629KZFXR5"
conditions: []
select_columns: []
limit: 100
```
**Output:**
```
rows: [
{"id": "1", "name": "Alice", "age": 30, "status": "active"},
{"id": "2", "name": "Bob", "age": 25, "status": "inactive"},
...
]
total: 250
```
### Example 2: Filter by Single Condition
**Input:**
```
dataset: "01K8ZM9T72FNBZAGA629KZFXR5"
conditions: [
{
"column": "status",
"operator": "equals",
"value": "active"
}
]
limit: 50
```
**Output:**
```
rows: [
{"id": "1", "name": "Alice", "age": 30, "status": "active"},
{"id": "5", "name": "Charlie", "age": 28, "status": "active"}
]
total: 120
```
### Example 3: Multiple Conditions with AND Logic
**Input:**
```
dataset: "01K8ZM9T72FNBZAGA629KZFXR5"
conditions: [
{
"column": "status",
"operator": "equals",
"value": "active"
},
{
"column": "age",
"operator": "greater_than",
"value": "25"
}
]
logic: "and"
select_columns: ["name", "age", "status"]
sort_by_column: "age"
sort_order: "desc"
limit: 20
```
**Output:**
```
rows: [
{"name": "Alice", "age": 30, "status": "active"},
{"name": "Charlie", "age": 28, "status": "active"}
]
total: 45
```
### Example 4: Using IN Operator
**Input:**
```
dataset: "01K8ZM9T72FNBZAGA629KZFXR5"
conditions: [
{
"column": "department",
"operator": "in",
"value": "sales,marketing,support"
}
]
limit: 100
```
**Output:**
```
rows: [
{"id": "1", "name": "Alice", "department": "sales"},
{"id": "2", "name": "Bob", "department": "marketing"},
{"id": "3", "name": "Charlie", "department": "support"}
]
total: 78
```
### Example 5: Contains Search
**Input:**
```
dataset: "01K8ZM9T72FNBZAGA629KZFXR5"
conditions: [
{
"column": "email",
"operator": "contains",
"value": "@company.com"
}
]
select_columns: ["name", "email"]
limit: 50
```
**Output:**
```
rows: [
{"name": "Alice", "email": "alice@company.com"},
{"name": "Bob", "email": "bob@company.com"}
]
total: 156
```
## Common Use Cases
* **Data Retrieval**: Fetch specific records from datasets based on business logic
* **Search Functionality**: Implement search features using contains operator for text matching
* **Analytics and Reporting**: Extract filtered data subsets for analysis and visualization
* **Data Export**: Query and prepare data before exporting to external systems
* **Workflow Triggers**: Find records matching specific criteria to trigger downstream actions
* **Pagination**: Use limit and total to implement paginated data views in applications
* **Multi-Condition Filtering**: Combine multiple filter criteria with AND/OR logic for complex queries
* **Sorted Results**: Retrieve data in specific order for ranking or time-based analysis
## Error Handling
| Error Type | Cause | Solution |
| ------------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
| Dataset Not Found | Dataset ID doesn't exist | Verify the dataset ID is correct and the dataset exists |
| Invalid Column | Column name in condition doesn't exist | Check available columns in the dataset schema |
| Invalid Operator | Operator value not in allowed list | Use one of: equals, not\_equals, contains, greater\_than, less\_than, in |
| Sort Column Not Selected | sort\_by\_column not in select\_columns | Include sort column in select\_columns or leave it empty |
| Invalid Limit | Limit outside 1-1000 range | Set limit between 1 and 1000 |
| Empty Dataset | Dataset has no rows | Verify dataset has been populated with data |
| Invalid Logic | Logic value not 'and' or 'or' | Use either 'and' or 'or' for logic parameter |
| Malformed Condition | Missing required fields in condition | Ensure each condition has column, operator, and value |
## Notes
* **Performance**: Use select\_columns to retrieve only needed fields for better performance with large datasets.
* **Pagination**: The total field shows all matching records, while rows respects the limit for pagination implementation.
* **Dynamic Dropdowns**: The dataset, select\_columns, and sort\_by\_column fields dynamically populate based on your available datasets and their schemas.
* **IN Operator Format**: For the 'in' operator, values can be comma-separated ("val1,val2,val3") or JSON array format (\["val1","val2","val3"]).
* **Empty Conditions**: If conditions array is empty, all rows from the dataset will be returned (subject to limit).
* **Limit Range**: Maximum limit is capped at 1000 rows per query for performance and resource management.
* **Case Sensitivity**: The contains operator behavior may vary based on database configuration. Test with your specific dataset.
* **Null Values**: Be aware of how comparison operators handle null values in your dataset columns.
* **Query Optimization**: For frequently accessed queries, consider creating filtered views or using appropriate indexes on dataset columns.
---
# 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://docs.agenticflow.ai/reference/nodes/query_data.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.