Guru Query Language
Filter card queries with Guru Query Language expressions, from dates to tags to verification state.
Guru Query Language lets you build complex filters for card queries, similar to WHERE clauses in SQL. Pass a query in the q parameter of the List Cards endpoint.
There are two kinds of expressions. Simple expressions operate on a single field, usually with an operator and a value, like lastModified > 2016-01-01T00:00:00.000-00:00. Grouping expressions link simple expressions with AND and OR, like (lastModified < 7_days_ago AND lastModifiedBy = "[email protected]"). Parentheses control operation grouping.
Legacy board namingThe
boardCountandboardsfields retain their legacy board naming from before Guru's transition from boards to folders. They operate on folders.
Absolute date expressions
Compare a date field to an absolute date value.
| Fields | dateCreated, lastVerified, lastModified, firstCommentCreatedEvent, lastCommentCreatedEvent, firstCopiedEvent, lastCopiedEvent, firstViewedEvent, lastViewedEvent |
| Operators | >, >=, <, <= |
| Value | A date in an ISO-8601 format (timezone required): yyyy-MM-ddZ, yyyy-MM-ddTHH:mmZ, yyyy-MM-ddTHH:mm:ssZ, or yyyy-MM-ddTHH:mm:ss.SSSZ (for example, 2015-02-01T15:01:30+04:00) |
Examples:
dateCreated >= 2016-01-01T00:00+00:00- the card was created after January 1st, 2016 at midnight UTClastViewedEvent < 2016-10-15T+00:00- the card was last viewed before October 15th
Relative date expressions
Compare a date field to a relative time range, such as finding all cards modified in the last three days.
| Fields | dateCreated, lastVerified, lastModified, firstCommentCreatedEvent, lastCommentCreatedEvent, firstCopiedEvent, lastCopiedEvent, firstViewedEvent, lastViewedEvent |
| Operators | >, >=, <, <= |
| Value | X_days_ago, where X is a positive integer. days is the only unit available. |
Examples:
lastModified < 7_days_ago- cards that were modified in the last weeklastViewedEvent > 30_days_ago- cards that haven't been viewed in the last 30 days
Card type expressions
Specify whether to return cards or questions.
| Fields | type |
| Operators | =, != |
| Value | CARD or QUESTION |
Example: type = CARD - only show cards, not questions
Verification interval expressions
Compare the card's verification interval to a number of days.
| Fields | verInterval |
| Operators | =, !=, >, >=, <, <= |
| Value | Number of days, positive integers only |
Example: verInterval = 7 - cards that must be verified every 7 days
Count expressions
Compare numeric fields of a card.
| Fields | boardCount (the number of folders a card is in), favoriteCount, commentCount, copiedCount, viewedCount |
| Operators | =, !=, >, >=, <, <= |
| Value | A positive integer |
Examples:
viewedCount > 5- cards that have been viewed more than 5 timesboardCount = 0- cards that aren't in any folder
File attachment expressions
Filter for cards that have or do not have file attachments.
| Fields | hasFileAttachment, hasNoFileAttachment |
Example: hasFileAttachment - returns cards that have a file attachment
File attachment type expressions
| Fields | fileAttachmentType |
| Operators | =, != |
| Value | Any media type, like application/pdf, application/vnd.ms-powerpoint, or text/plain |
Example: fileAttachmentType = "application/pdf" - cards with PDF attachments
Tag category expressions
Filter cards that have or don't have tags from a specific tag category.
| Fields | tagCategory-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where the suffix is the ID of the tag category. Use Get all tag categories to find tag category IDs. |
| Operators | exists, notExists |
Example: tagCategory-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx exists
Tag expressions
Filter cards that have or don't have a specific tag.
| Fields | tag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where the suffix is the ID of the tag. Use Get all tag categories to find tag IDs. |
| Operators | exists, notExists |
Example: tag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx exists
User expressions
Filter cards associated with a specific user.
| Fields | creatorId (user that created the card), verifierId (user responsible for verifying the card), lastVerifiedBy (user that last verified the card), lastModifiedBy (user that last modified the card) |
| Operators | =, != |
| Value | The email address of the user |
Example: creatorId = "[email protected]" - cards created by Gary
Group expressions
Filter cards associated with a specific group.
| Fields | verifierId (group responsible for verifying the card) |
| Operators | =, != |
| Value | The ID of the group |
Example: verifierId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - cards this group is responsible for verifying
Verification state expressions
Filter cards by verification state.
| Fields | verificationState |
| Operators | =, != |
| Value | trusted, needsVerification |
Example: verificationState != trusted - cards that are not trusted
Share type expressions
Filter cards based on their visibility.
| Fields | shareType |
| Operators | =, != |
| Value | TEAM, PRIVATE, or PUBLIC |
Example: shareType = PRIVATE - all cards that are private
Board expressions
Filter cards based on a folder the card is in.
| Fields | boards |
| Operators | CONTAINS |
| Value | The folder ID |
Example: boards CONTAINS ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") - cards in the folder with that ID
Updated 20 days ago