Guru Query Language

Guru's query language allows for complex queries to be constructed to filter card queries in a manner similar WHERE clauses found in SQL. There are two types of expression; simple expressions and grouping expressions.

Simple expressions operate on a single field and usually contain some sort of operator and a value. For example lastModified > 2016-01-01T00:00:00.000-00:00.

Grouping expressions support AND and OR operations to link two or more simple expressions together into a complex expression. For example, (lastModified < 7_days_ago AND lastModifiedBy = "[email protected]" ) would show all cards that have been modified in the last seven days by the specified user. Parenthesis can be used to ensure proper operation groupings.

Absolute Date Expressions

Used to compare a date field to an absolute date value.

Fields: dateCreated, lastVerified, lastModified, firstCommentCreatedEvent, lastCommentCreatedEvent, firstCopiedEvent, lastCopiedEvent, firstViewedEvent, lastViewedEvent
Operators: >, >=, <, <=
Value: A date value in one of the following ISO-8601 formats. NOTE - timezone is required for all formats
yyyy-MM-ddZ (i.e. 2015-02-01+04:00)
yyyy-MM-ddTHH:mmZ (i.e. 2015-02-01T15:01+04:00)
yyyy-MM-ddTHH:mm:ssZ (i.e. 2015-02-01T15:01:30+04:00)
yyyy-MM-ddTHH:mm:ss.SSSZ (i.e. 2015-02-01T15:01:30.000+04:00)

Examples

dateCreated >= 2016-01-01T00:00+00:00 - the card was created after January 1st, 2016 at midnight UTC
lastViewedEvent < 2016-10-15T+00:00 - the card was last viewed before October 15th

Relative Date Expressions

Used to compare a date field to a relative time range. For example, finding all cards that have been modified in the last three days.

Fields: dateCreated, lastVerified, lastModified, firstCommentCreatedEvent, lastCommentCreatedEvent, firstCopiedEvent, lastCopiedEvent, firstViewedEvent, lastViewedEvent
Operators: >, >=, <, <=
Value: A relative date expression of the form X_days_ago where X is a positive integer. At this time, days is the only unit available for the relative date expression.

Examples

lastModified < 7_days_ago - cards that were modified in the last week
lastVewedEvent > 30_days_ago - cards that haven't been viewed in the last 30 days

Card Type Expression

Used to specify whether to return cards or questions.

Fields: type
Operators: =, !=
Value: CARD or QUESTION

Examples

type = CARD - only show cards, not questions

Verification Interval

Used to compare the card's verification interval to a number of days

Fields: verInterval
Operators: =, !=, >, >=, <, <=
Value: Number of days, positive integers only

Examples

verInterval = 7 - cards that must be verified every 7 days

Count Expressions

Used to compare numeric fields of a card

Fields: boardCount (number of boards a card is on), favoriteCount (number of times a card has been favorited), commentCount, copiedCount, viewedCount
Operators: =, !=, >, >=, <, <=
Value: A positive integer

Examples

viewedCount > 5 - cards that have been viewed more than 5 times
boardCount = 0 - cards that aren't on a board

File Attachment Expressions

Used to filter for cards that have or do not have file attachments

Fields: hasFileAttachment, hasNoFileAttachment

Examples

hasFileAttachment - returns cards that have a file attachment

File Attachment Type

Fields: fileAttachmentType
Operators: =, !=
Values: Any media type, like application/pdf or application/vnd.ms-powerpoint or text/plain

Examples

fileAttachmentType = "application/pdf" - cards with PDF attachments

Tag Category Expressions

Used to filter cards that have or don't have Tags from a specific Tag Category.

Fields: tagCategory-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is the ID of the Tag Category. Use the Tag List call to find all Tag Category IDs
Operators: exists or notExists

Examples

tagCategory-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx exists

Tag Expressions

Used to filter cards that have or don't have a specific tag.

Fields: tag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is the ID of the Tag. Use the Tag List call to find all Tag IDs.
Operators: exists or notExists

Examples

tag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx exists

User Expressions

Used to filter cards associated with a specific user.

Fields: creatorId (user that created the card), verifierId (user that is responsible for verifying the card), lastVerifiedBy (user that last verified the card), lastModifiedBy (user that last modified the card)
Operators: = or !=
Values: The email address of the user

Examples

creatorId = "[email protected]" cards created by Gary

Group Expressions

Used to filter cards associated with a specific group

Fields: verifierId (group that is responsible for verifying the card)
Operators: = or !=
Values: The ID of the group

Examples

verifierId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx" the group with ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is responsible for verifying this card

Verification State

Used to filter cards by verification state

Fields: verificationState
Operators: = or !=
Values: trusted, needsVerification

Examples

verificationState != trusted cards that are not trusted

Share Type Expressions

Used to filter cards based on their visibility

Fields: shareType
Operators: = or !=
Values: TEAM or PRIVATE or PUBLIC

Examples

shareType = PRIVATE - show all cards that are private.

Board Expressions

Used to filter cards based on a Board that the card is on

Fields: boards
Operators: CONTAINS
Value: the board ID

Examples

boards CONTAINS ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") - cards that are on the board with ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx