Actions31
- Option Set Actions
- Public Query Actions
- Record Actions
- Role Actions
- Workflow Actions
- Worksheet Actions
Overview
This node interacts with the HAP (Hyper Application Platform) API to retrieve multiple records from a specified worksheet. It supports advanced filtering, sorting, pagination, and field selection, making it useful for scenarios where users need to query large datasets efficiently and flexibly.
Typical use cases include:
- Extracting filtered lists of records based on complex conditions.
- Paginating through large record sets.
- Selecting specific fields to optimize data transfer.
- Sorting records by one or more fields.
- Performing keyword fuzzy searches within records.
- Retrieving data in either table view format or raw JSON structure.
For example, a user might want to fetch all customer records from a worksheet where the customer's name starts with "张" and the date is within January 2025, sorted by creation date descending, returning only certain fields.
Properties
| Name | Meaning |
|---|---|
| Worksheet ID | The unique identifier of the worksheet from which to retrieve records. |
| Page Index | The page number to retrieve, starting from 1. Used for paginated results. |
| Page Size | Number of records per page, with a maximum limit of 1000. Controls the size of each page in pagination. |
| View ID | Optional filter to restrict records to a specific view within the worksheet. |
| Fields | JSON array of field IDs to return. If empty, all fields are returned. Allows selecting only needed fields to optimize response size. Example: ["field1", "field2"]. |
| Filter | JSON object defining complex filtering logic. Supports nested groups with AND/OR logic and conditions using 22 supported operators such as equals, not equals, greater than, contains, between, isempty, etc. Conditions specify field IDs, operators, and values. Enables precise querying of records matching complex criteria. Example: {"type": "group", "logic": "AND", "children": [{"type": "condition", "field": "name", "operator": "startswith", "value": "张"}, {"type": "condition", "field": "date", "operator": "between", "value": ["2025-01-01", "2025-01-31"]}]}. |
| Sorts | JSON array specifying sort configurations. Each item includes a field ID and a boolean indicating ascending (true) or descending (false) order. Example: [{"field": "field_id", "isAsc": false}]. |
| Search | Keyword string for performing a fuzzy search across records. |
| Table View | Boolean flag indicating whether to return data in a table view format (structured tabular data) or raw JSON. Defaults to true. |
| Use Field ID as Key | Boolean flag determining if the output keys should be field IDs instead of their aliases. Defaults to true. |
| Include Total Count | Boolean flag to include the total count of records matching the query in the response. Useful for pagination UI. Defaults to true. |
| Include System Fields | Boolean flag to include system-generated fields in the response. Defaults to false. |
Output
The node outputs an array of records in the json property of each item. Each record contains key-value pairs representing fields and their values according to the requested fields and formatting options.
- If Table View is enabled, the data is structured in a tabular format suitable for direct consumption or display.
- Keys in each record correspond to either field IDs or aliases depending on the Use Field ID as Key setting.
- When Include Total Count is enabled, the output also includes metadata about the total number of records matching the query, aiding in pagination.
- System fields may be included if requested.
- No binary data output is indicated for this operation.
Dependencies
- Requires an API key credential for authenticating with the HAP API.
- The node expects network access to the HAP service endpoint.
- No additional external libraries beyond those bundled with the node are required.
- Proper configuration of the API authentication credential in n8n is necessary.
Troubleshooting
- Invalid Worksheet ID: If the worksheet ID does not exist or is incorrect, the API will likely return an error. Verify the worksheet ID is correct.
- Filter Syntax Errors: Filters must follow the specified JSON structure and use only supported operators. Invalid filters will cause request failures. Validate filter JSON carefully.
- Page Size Limits: Requesting a page size larger than 1000 may result in errors or truncated responses. Keep page size at or below 1000.
- Authentication Failures: Ensure the API key credential is valid and has sufficient permissions.
- Empty Results: If no records match the filter or search criteria, the output will be empty. Adjust filters or search terms accordingly.
- Field IDs vs Aliases: If output keys do not match expectations, check the Use Field ID as Key setting.
- Network Issues: Connectivity problems to the HAP API endpoint will cause execution failures.
Links and References
- HAP API Documentation (Replace with actual URL)
- n8n Documentation on Creating Custom Nodes
- JSON Filter Structure Examples (from property description)
If you need further details on other operations or resources, feel free to ask!