A query type tells a query which kind of record to list and which fields you can use. It defines what each row represents, such as a contact, membership, registration, or invoice line item. It also controls the fields available for criteria, output, and sorting. You choose the query type when you start a query, and you cannot change it later.
Choose the query type that matches the question you want to answer. Most missing-field issues and unexpected row counts happen when the query starts from the wrong kind of record.
Not every group of records can be joined in one query type. Finance and billing query types for external payments do not include membership fields, and membership query types cannot pull in external payment data, even when they include other financial fields. When your question spans two applications that are not joined in one type, choose the query type for your main dataset. Then run a second query for the remaining data and combine the results yourself.
Where Query Types Come From
When you choose New Query in a Query Center, the Select Query Type dialog shows categories on the left, the types in the selected category in the middle, and About this Query Type with a description on the right. Query types come from three places:
| Source | Where it appears | Example |
|---|---|---|
| The application's built-in types | Under the application's own categories | Membership offers types such as Memberships - All, Memberships - Principal, Historical Membership Snapshots, Chapter Roster/Memberships, and Committee Members (Current) |
| Custom query definitions set up for your organization | Under Custom | A query Rhythm has written for a specific need, such as a special join or a pre-filtered table |
| Your organization's queryable custom objects | Under Custom | A custom object, such as "Degrees" attached to membership applications, appears as a query type such as "Application Degrees" |
A membership query type scoped to "all" memberships counts both contacts and organizations. Because of that, the record count can be higher than you expect if you only want one kind of member. Choose a type scoped to the group you want, or add a condition that narrows the record type to only contacts or only organizations. Standard query types may not be able to join several related queryable custom objects into one query, such as objects that work together to build one kind of record. Ask Rhythm about a custom query definition when you need that kind of join.
Each application offers only its own query types. You can list the same people from several applications, but each application exposes the fields available through its own types. Build the query in the application that has the records and fields your question is about. For example, use Certifications when your report must be limited to people who hold a certification, because that application's query types include certification-specific criteria and output fields. Use the same approach in other applications.
Some query types are limited to one parent record, such as one event. When you choose one, a record picker appears under it and is labeled with the record type, such as Event. If (optional) appears, you can leave the picker empty. When you select a parent record, the query lists only rows for that record.
Some application-level registration query types, such as an exhibitor query, return one row per registration and do not split a linked order into line items. For example, an order with several booth-related line items does not show each purchased item as a separate value or row in that query. If you need each order line item on its own row, build the query on an order line item query type and narrow it to the event. In an exhibitor query, use the Order Balance Due output field, available from either the Exhibitor or Order group, to see the order's full balance. A balance field from a narrower part of the order may show only part of that balance.
The query type identifier, such as rolodex:contacts, appears as a tooltip on the three-dot icon beside a query's name. Integration developers use it when they run queries through the API. If you cannot find a type's identifier in the query tool, the API reference's query type list, such as collect:products, lists the identifiers available to your organization. When you start a saved query through the API, use the same record type as the query's definition. A request that uses a different type may be accepted without an error, but it will not run the query you expect. The request body must be valid JSON only, with no explanatory text before it, and its fields and criteria must match the endpoint you are calling. Otherwise, the query can fail to process and stay in SUBMITTED status. When you only need contact records, use the contacts query type, even if you also want to filter by membership status. The type should match the records you want returned, while the criteria can still reference related data, such as membership status, through that type's fields.
How the Field List Is Built
In the designer, the Add a field... picker and the Field Browser show every field the query type offers. Fields are grouped by the record they belong to. Rhythm builds that list each time from:
- The main record's fields. The list includes every standard field for the record type the query lists.
- Related records' fields. A type can include related records, such as a membership's contact, the contact's organization, a parent organization, or a primary chapter. Those fields appear under the related record's name. When you add one from
Add a field..., its column heading becomes<field label> (<group>). - Your custom fields. The list includes every custom field your organization has defined on the main record type or on a joined record type, under that record's group. Yes/No custom fields offer
YesandNo, and fields with a list of values offer that list. When you choose labels for a list field's values, avoid labels that use mostly the same words. Distinct labels are easier to target with text-based criteria and make reporting and segmentation simpler, with less need for layered inclusion and exclusion filters. A custom field name that points to a specific guest slot on a registration is only a naming convention. It does not create a relationship the query engine uses to tie that value to one guest line item, so the field remains a value on the record where it is defined. - Lookup values as pick lists. Fields that refer to a lookup, such as a membership type or chapter type, offer your organization's active values by name. Inactive values are not offered, and two values with the same name appear once.
- Readable names. A field that refers to several records, such as several categories, appears as one text field with the names separated by commas.
Pick the Field from the Record That Holds the Data
The same field name can appear in several groups, and each group reads a different record. A custom field shown under Contact, Organization, and Parent Organization reads three separate places. If a column is blank for most rows, check which group you selected and choose the group for the record that stores the value. To return a person's email address, choose the Email Address field under Contact. A similarly named field such as Email Address (Membership) reads a separate value stored on the membership record, and the two values do not have to match. Organization Name (Contact) is a text snapshot saved on the contact, while Organization (Contact) reads the contact's linked organization record as a pick list. Because those fields can behave differently in criteria, choose the linked field when you want the current organization record. When you run a query directly on a record type such as Installment Schedules, choose the identifier and other fields from that record's own group instead of a similarly named field under a related record such as Order. In that context, using the related-object field can leave the column blank. A group heading in the Field Browser names the related record a field comes from; it does not change the query type or dataset you are working in. Do not treat a group name as a sign that you are in the wrong query. The wrong group's field can affect criteria as well as output columns, and it can make a query return no matching rows even when matching records exist. Check each condition's field as well as each output column. A field's presence in the builder also does not guarantee that its data is fully supported for that query type. If a field returns clearly wrong or empty values everywhere you expect data, treat it as a possible product issue rather than assuming your criteria are wrong.
The Field Browser search matches each field's internal name, not the label you see. If searching by label finds nothing, try a shorter word, or scroll the grouped Add a field... picker, which lists fields by label. For example, a contact's website sign-in details are easier to find by searching for "user" than for "login."
Membership Fields Can Add Rows to a Contacts Query
A contact can have more than one related membership record, such as an individual membership and an organization or flowdown-parent membership. When you add a Membership field to a Contacts query, the query can return one row per related membership instead of one row per contact. As a result, the same contact can appear more than once. The same behavior can happen in other query types when you add fields from a related record that can match more than once. For example, membership fields on an invoice line item query can return two rows for one line item when it relates to more than one membership record. Support has also seen a Contacts query filtered by membership status include a contact whose own Membership record shows inactive, especially for contacts with prior flowdown membership history. If you see this, run the equivalent query in Membership instead, which has returned the expected inactive result while this is investigated further.
The Field Browser search matches each field's internal name, not the label you see. If searching by label finds nothing, try a shorter word, or scroll the grouped Add a field... picker, which lists fields by label. When field labels in the criteria selector are too small or too similar to tell apart, use the Field Browser on the left side of the query sidebar as a workaround. Filter it by typing a term, such as a prefix for the group you want, then use that list to identify the field to add. Email address is not part of every query type's default output columns, so you may need to add it yourself from Add a field... or Field Browser even when other contact details are already selected.
To share query results with an outside vendor or system through the API, build the query in the application whose records and fields match your need. Review the available fields in Field Browser, and save the query under your organization's queries instead of your private queries so others, including integrations, can use it. Run it once to confirm the output, then see the public API documentation for how an integration retrieves it.
Columns That Appear Only in Some Circumstances
Some query types include extra columns that Rhythm turns on for each organization. If your organization does not have them, they do not appear in the field list. This setting applies to your organization as a whole, not to individual records, and every row in the table below depends on it. If you do not see columns you expect, such as coupon fields on order queries, contact-role fields on organization queries, or portal sign-in fields on contact queries, ask Rhythm to confirm whether they are switched on for your organization.
| Columns | Added to | Conditions |
|---|---|---|
| One set per address type, including line 1 to 3, city, state, postal code, county, country, latitude, and longitude, and one set per phone number type | Contact and organization query types | One set appears for each type your organization has defined, whether active or not |
| Per communication type: enabled, subscription email, last updated, and status | Contact query types | One set appears for each communication type |
| Participation in chosen events, courses, and committees, such as registered, registration type, amount paid, position, and term dates | Contact query types | Administrators choose the events, courses, and committees in the organization's contact settings. Those fields then become available for you to add to any contact query, but they are not automatically included as default output columns. Rhythm skips an item if it has been deleted since it was chosen |
| Engagement category, score, percentile rank, and year-over-year change | Contact and organization query types | Engagement scoring is switched on. Rhythm uses only the current month's scores, so the columns are empty early in a month before scores are calculated |
Portal - # of Logins, Portal - Last Login Date, Portal - Last Login IP Address | Contact query types | Sign-ins are totaled across all of the contact's portal sign-in credentials. The IP address comes from the credential changed most recently, which is not necessarily the credential used for the latest sign-in. A contact with no portal credential shows 0 and blanks. These fields have been observed to populate only when your organization's portal uses direct sign-in. If your portal uses another sign-in method, they may show blank or zero even for a contact who has signed in. To check, test with a contact who signs in directly through your portal |
| One column per session, function, and add-on | Event registration types | The query is narrowed to one event. Detailed session and function reporting, such as attendance or amounts paid per session, is retrieved this way rather than through one combined event-registration query type. If you need that level of detail, add these columns instead of looking for them on a general registration list |
| Portal - # of Logins, Portal - Last Login Date, Portal - Last Login IP Address | Contact query types | Sign-ins are totaled across all of the contact's portal sign-in credentials. The IP address comes from the credential changed most recently, which is not necessarily the credential used for the latest sign-in. A contact with no portal credential shows 0 and blanks. These totals may not reflect activity from before your organization started tracking portal sign-ins, so treat a low count with caution. A record's security information, or your identity provider's sign-in history, can show earlier activity that these columns do not | | Accreditation teams, most recent site visit, candidate status, and accreditation status | Contact and organization query types | Your organization uses the accreditation application. One set appears per active program | | # of Contacts, # of Organizations, and per contact role: name, email address, and phone number, plus any extra contact field an administrator has added to that role's setup | Organization query types | Active contact roles only. The base three columns are always name, email address, and phone number. Extra fields must belong to the contact itself or be contact custom fields, so fields such as ID, prefix, legacy prefix, and last name appear only if an administrator has added them to that role's extra-field setup | | Coupon code IDs, coupon IDs, and coupon types | Types that include orders | Identifiers, not names, separated by commas | | Readable product type names | Types that include products | A fixed list of product types |
Custom address types your organization defines for organizations now appear in the field browser the same way built-in address types do. They did not always show there, but that has been fixed. Address columns return each part separately. There is no single output field for a complete work address, or any other complete address, in one value. Add the columns you need, such as line 1 to 3, city, state, postal code, and country. If a mailing query is using addresses marked preferred instead of a specific type, remove the preferred-address fields in the designer and add the fields for the address type you want, such as work. Latitude and longitude are stored and queryable for several record types, including contacts, organizations, events, and orders, wherever that record's query types offer address fields. You cannot see or edit them directly on a record; they exist only for queries, and Rhythm does not provide a built-in map that plots them. To map them, export the coordinates into a mapping tool. Country-based filtering, and any region logic that depends on it, uses the structured Country field. Country text typed somewhere else in the address, such as a street-address line, does not count.
Do Not Mail and Do Not Mail Guardian Magazine are contact fields that can exclude a contact from a mailing-list query's results. You can query on either field even if your organization's contact forms do not show it on the Contact 360 screen, because forms and query availability are configured separately. If mailing counts look inconsistent between similar filters, check whether the field's values were imported. A migration or import can leave some records blank and others explicitly set to No for the same field. A query that treats blank and No differently returns different populations depending on which value those records have.
Choosing between a Contacts query and an Organization query changes which records you get when contact roles are involved. A Contacts query built around a role returns only contacts who have that role. An Organization query returns every organization, including organizations with nobody assigned to the role, and lets you add the role's fields as extra columns. Use the Organization query type when you need a complete list of organizations regardless of who holds a role. Use a Contacts query focused on that role when you need fuller detail about the role-holder, because role-based columns from an Organization query type carry only a limited set of contact fields. This choice matters for reporting that spans membership, finance, and CRM data, such as pulling membership invoices together with the related organization and its role-based contacts. Start from the query area whose type includes both the records and fields you need, and add related-record fields instead of trying to make one type answer every question. Organization query types, and other query types that reference organizations, such as membership, can also expose organization-derived fields like address types, phone number types, engagement information, contact count, and child organization count. If adding an organization-category contact role field as an output column produces Unable to preview query, remove it. Rhythm is aware that some organization-level contact role fields can fail to preview.
Being able to query a specific contact role, or any other field, does not mean the same value is available as a merge field in notice templates. Query fields and notice-template merge fields are separate capabilities, and support for one does not automatically mean support for the other.
Build person-focused queries in Contacts, then add the accreditation columns you need. Those columns work the same way whether the query starts from Contacts or Organizations. Accreditation identifiers you might expect, such as a candidate's own record identifier, are not always available as selectable columns in every application's query context. When a field genuinely cannot be added to any query type that has the records you need, export two separate queries, one for each side of the data, and combine them outside Rhythm, such as in a spreadsheet with a lookup formula matched on a shared identifier.
Date-Only Custom Fields Can Show a Time in Query Results
A custom field configured as Date, not Date Time, should show only a date. Rhythm has seen cases where a query still displays a time such as 12:00 AM for that field, or where filtering it with a date-only criterion returns no results because the stored value carries a hidden time. If a date-only custom field behaves this way, treat it as a known issue and contact Support instead of assuming your data or criteria are wrong.
A field tied to an integration your organization no longer uses can remain visible and selectable in the field browser after that integration is retired. It will not return new data. If a field clearly relates to a discontinued integration and never returns values, that reflects the retired integration, not a broken query.
Why You Cannot Find a Field
Check these in order:
You started on a different query type. Each type offers only the fields from its own records and the records it joins, so a field in one type may be missing from a similar-sounding one. For example,
Product (Financial Configuration)is available only when the query type isPayment Line Items with Products, not on other payment or invoice types. To isolate membership invoices from other invoice types, such as event invoices, use anInvoice Line Items with Productsquery type and filterProduct TypeforMembership Packages. APayment Line Items with Productsquery can also help you find dues-related payments by filtering the invoice line item for text such as "dues." That approach does not filter by membership status or expiration, and it is not limited to current or lapsed members. ReadAbout this Query TypeinSelect Query Type, then start a new query on the type whose rows you want.The field is under a related record's group. Look under the group for the contact, organization, parent organization, chapter, or order. Not every related record's fields are available everywhere that record is joined. For example, chapter custom fields are available in chapter queries, but not in committee queries, even though committees relate to chapters.
It is one of the conditional columns above. Check the conditions in the table.
The custom field or custom object is new. A custom field you add, change, or delete is reflected within moments. Custom fields and custom objects created by a data import appear only after Rhythm's nightly refresh. A custom object appears as a query type only after querying is switched on for it and its setup has completed; see Custom Objects.
The data is not queryable. Not everything shown on a record screen is offered as a query field. The field list contains exactly what the query type offers.
The field's own setup needs resaving. If a custom field you know exists still does not appear in the field list, open its setup and save it again without changing anything. This workaround has cleared up the problem in some cases, but it is not a guaranteed fix.
The custom field or custom object is new. A custom field you add, change, or delete is reflected within moments. Custom fields and custom objects created by a data import appear only after Rhythm's nightly refresh. A custom object appears as a query type only after querying is switched on for it and its setup has completed; see Custom Objects. Support sometimes describes re-syncing the data behind queries to its source as a "snapshot." That refresh is different from the
Historical Membership Snapshotsquery type, which preserves a point-in-time copy each month. After that refresh completes, query data goes back to updating in near real time.The data is not queryable. Not everything shown on a record screen is offered as a query field. The field list contains exactly what the query type offers, so information visible on a record's page, including a record's history, is not automatically available for querying or reporting just because it appears in the UI or in an API response. For example, no query field returns the email address of the user recorded in a record's
Created Byfield. A query can tell you a record's last-modified date and who last updated it, but not which specific fields changed. A field Support references while troubleshooting is not automatically available to add in every screen that lists fields, including advanced search.The activity is missing an activity type, or it came from an import. Contact Activity query results depend on the underlying activity record having an activity type. Some activities shown on a contact came from an import and cannot be edited on the front end. If one is missing an activity type, it may not appear in Contact Activity query results.
Certification fields are not exposed on contact query types the way membership fields are, so a single query that mixes contact-side and organization-side certification criteria may not be practical. Build separate queries for the contact certification criteria and the organization certification criteria, in the application that owns each side.
A few specific field problems are worth knowing. An invoice-related ID field has sometimes returned a blank column even when the record has a value. If that happens, use the field named ID under Invoice Line Item in the Field Browser instead. A saved query's existing Product output column can go blank if the field it points to no longer matches a real product field. If this happens, open the query in the designer and reselect the Product field. After a multiselect custom field's option label is corrected, records that stored the field before the correction can keep the old text. A query built around the corrected label may not match those older records until they are resaved. The query Field Browser can also show a contact custom field for a short time after a data import even though the field is no longer in your custom field setup. This clears up once Rhythm's field metadata catches up. If an existing custom field disappears from a query's available output fields, ask Rhythm to resave and refresh it. A problem in a custom field's definition can also break every saved query that uses it, for every user, along with any API call that references the same field, until the field is corrected and resaved. If a query shows a person but leaves standard contact fields blank, the contact record may be out of sync. Opening the contact and saving it again, even without changes, can restore the missing data the next time the query runs.
Use Sys Created At to filter by when a record was first created in Rhythm, and use Sys Last Modified At for when it last changed. When you need to know exactly when something happened, such as the precise time an application was submitted, use a timestamp field such as Submission Date, Sys Created At, or Sys Last Modified At instead of a date-only field, which does not carry a time.
New built-in query types that Rhythm releases can take up to ten minutes to appear. A lookup value you add, rename, or deactivate reaches the pick lists within moments. Product type names change only when Rhythm updates the fixed list.
When Fields Change or Disappear
Adding or changing a field never requires a database rebuild on your side. A query's field list is built from your organization's current field definitions each time, so a new or additive field is normally ready to query within moments rather than after a migration.
If a custom field is deleted, it disappears from the field list. A saved query that includes that field in results or sorting keeps running and leaves that column out, without warning. A saved query that uses the field in criteria fails when it runs. Open the query in the designer and replace or remove the condition; see Save a Query and Organize Folders. Before you delete a field, check other queries for references to it. If you still need the field afterward, you have to recreate its definition and add it back to each query that used it.
Related
- Design and Run a Query
- Query Criteria and Filter Operators
- Query Results: Fields, Sort, Paging, and File Formats
- Custom Fields Explained
- Data Dictionary and Record Relationships