Every query in Rhythm follows the same fixed rules, whether you run it in Query Center, schedule it for delivery, or run it through the API. These rules apply to every organization, and they cannot be changed.
Limits
| Limit | Value | What happens when exceeded |
|---|---|---|
| Output columns | At most 255, including one column Rhythm always adds to identify each row | Rhythm refuses the query with Too many output fields |
| Distinct fields across output and sort together | At most 255 | Rhythm refuses the query with Too many output and sort fields. If the query exceeds both limits, Rhythm reports only Too many output fields |
| Fields used only in criteria | Not counted toward either limit | — |
| Sort fields in the query designer | At most 5 | Add Another Sort Field becomes unavailable |
| Preview in the designer | At most 10 rows | Run the query to see every row |
| Page size and starting row (API) | No maximum | — |
| Delivery schedule frequency | No more than once an hour | Rhythm does not save the schedule |
Outstanding Balance and Query Size
If your Rhythm account has an outstanding balance, you cannot run a query that would return more than 200 results. Rhythm refuses the query with a generic execution error, not a message that names the balance as the cause, so an affected saved query can look like it has stopped working. Pay the outstanding balance to restore normal query execution; you do not need to change the query.
Queries List Records; They Do Not Count Them
A query returns records, with one row for each record. It cannot count, total, average, or group records, so it cannot return “the number of active members in each chapter” as one row per chapter. If you ask a query to count records, Rhythm refuses it with The query engine no longer supports aggregate queries. Please use statistics endpoints.
What you can do:
- Use the record counts Rhythm already gives you. Query Results shows
<n> records returned, a formatted Excel file includes the number of records in row 2, and each saved query shows itsRecord Count. - Run one query for each group, such as one query per chapter, or narrow the criteria to the group you need.
- Download the rows, then count or total them in a spreadsheet.
- Remove duplicate rows yourself if needed. Rhythm does not have a built-in way to remove duplicates from query results, so download the rows and use Excel, Google Sheets, or another spreadsheet program to find and remove them.
Your Organization's Records Only
Every part of every query stays within your organization’s records, including the main records and any related records joined to them. A query cannot return another organization’s data, and you cannot see another organization’s queries, progress, or results. If you use an identifier from another organization, Rhythm responds as if that identifier does not exist.
Within your organization, anyone who has the identifier for a background query can look up its progress and results.
For how your Rhythm account, customers, and sandboxes fit together, see Your Rhythm Account, Customers, and Sandboxes.
How Long Answers and Links Last
| Item | How long it lasts |
|---|---|
| A download from Query Results | Each download runs the query again and opens a fresh file right away. The link behind it works for 15 minutes |
| A download link obtained through the API | 15 minutes. Ask for the query’s status again to get a fresh link |
| The link in a scheduled delivery email | 30 days, without signing in |
| The answer file and the record of a background query | About 30 days after Rhythm writes them. After that, the query’s status is not found, and links point to nothing. Answers cannot be kept longer or removed sooner |
Keep a copy of any file you need beyond 30 days.
How Queries Run
- Each run is a snapshot. The answer reflects the records as they were when the query ran. It does not update later, so run the query again when you need current data.
- New or changed records are not always queryable the instant you save them. A record always takes some time to become available to a query. In most cases, the record is available within seconds, but under heavy load it can take 5 to 10 minutes. This delay applies broadly across applications because queries share the same underlying engine, so it can also affect KPI tiles, dashboard widgets, and other report-like views, not just the query results screen. If a downstream process depends on a query result right after a record is created, such as an integration that runs as soon as a record is saved, build in tolerance for this delay.
- Query results can occasionally lag further behind that. Beyond the normal few-minutes delay, saved query results have occasionally lagged behind recent record changes for longer while background query processing catches up, including after a large bulk update. For example, a mass correction to postal codes has been observed to show correctly on individual records immediately, while a query on those same records still showed the old value for a while before catching up. A query built around stored card expiration dates has also been known to skip some eligible records. If you notice results like this, compare a few affected records’ own screens with the query output and note the times you checked them. That is the most useful information to send Support if the problem does not clear on its own.
- KPI tiles refresh on their own schedule, separate from when records become available to queries. Most KPIs refresh once a day, though some refresh as often as every 10 minutes, and a KPI can take up to about an hour to fully reflect a recent change. Use the KPI’s own refresh control if you need it to show the latest count right away.
- Every run is new. Each time you run or start the same query, Rhythm runs it again and creates a separate answer. You cannot cancel a query after it has started.
- Large queries can run in the background. A background query gives you an identifier right away and provides the answer when it finishes. At busy times, background queries can wait their turn before they start. A query run synchronously can time out if it runs too long. For a long-running query through the API, such as a large certification export, use the asynchronous path and a query rather than a direct record-returning call, since a query is not limited by the same response-size constraints.
- The asynchronous API path is a start-then-check flow. Post the query to start it, then poll its status using the identifier you received. If you check the status immediately after you start the query, it usually still shows as in progress with no result yet. Keep checking until it reports finished, then download from the link in that response. If you retrieve results through a paginated API, retrieve every page rather than stopping after the first, or your results can look incomplete.
- Very large answers can take too long. A very large answer can fail to finish converting to a file, especially as a formatted spreadsheet. Narrow the criteria, remove columns you do not need, or split the query, for example by date range.
- Relative dates are worked out when the run starts, from the current time in UTC. See Query Criteria and Filter Operators.
Related
- Query Results: Fields, Sort, Paging, and File Formats
- Query Criteria and Filter Operators
- Run Queries from Integrations and Workflows (coming to the developer documentation)
- Your Rhythm Account, Customers, and Sandboxes