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 = "[e-mail]" ) 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

1. dateCreated >= 2016-01-01T00:00+00:00 - the card was created after January 1st, 2016 at midnight UTC
2. 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

1. lastModified < 7_days_ago - cards that were modified in the last week
2. 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

1. 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

1. 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, viewedCountOperators: =, !=, >, >=, <, <= Value: A positive integer

Examples

1. viewedCount > 5 - cards that have been viewed more than 5 times
2. 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

1. 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

1. 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 Listcall to find all Tag Category IDs Operators: exists or notExists

Examples

1. 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

1. 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

1. creatorId = "[e-mail]" 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

1. 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, stale, needsVerification

Examples

1. 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

1. 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

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