Hire WorkforcePython SDKRequest DemoDocumentation
Documentation
Start typing to search…

Queries

queries

When you’re in the Explore tab, you'll see a query search bar above your items. This bar takes JSON queries that'll allow you to search for items in your project that match any given criteria. To see information about queries regarding Multimodal projects, read here.

Here are some example queries you can try out:

FunctionQuery
To search for items that have instances that are polygons and are assigned to the classes car or pedestrian.instance(type = polygon AND className IN [Car, Pedestrian])
To search for items that have unresolved comments.comment(resolved = false)
To search for items that contain Bounding Boxes.instance(type = bbox)
To search for items that contain instances with the class Car.instance(className = Car)
To search for items that have the Completed status and are located in Folder1.metadata(status = Completed) AND folder = Folder1
To search for items that contain more than 3 instances with the class Car and the attribute Black.instanceCount(className = Car AND attributes.name = Black) > 3
To search for pinned items.metadata(pinned = true)

Operators

You'll need to use operators to define your queries and values.

OperatorDescription
=Equal.
!=Not equal.
>Greater than.
<Less than.
>=Greater than or equal to.
<=Less than or equal to.
()Query parentheses.
[]Array.
ANDReturns True if both statements are true.
ORReturns True if either statement is true.
INSet of values to consider.
NOT INSet of values to not consider.
CONTAINSUsed to search for a substring and returns the results containing that substring. All text queries made with this operator are case-insensitive.

📘

When the attribute has a numeric type, the following operators will be supported for attributes.name: > < =< !=

Instance

These parameters can be found under the instance field.

Parameter

Value

Text

Image

Video

type

bbox, polygon, polyline, point, ellipse, cuboid, rbbox, tag and relationship.

✅

✅

✅

className

The value is a class's name.

✅

✅

✅

attribute.name

The value is an attribute's name.

✅

✅

✅

attribute.groupName

The value is an attribute group's name.

✅

✅

✅

error

true, false, or null.

❌

✅

❌

createdBy.email

The value is an email address.

✅

✅

✅

createdBy.role

Annotator, QA or Admin.

✅

✅

✅

creationType

Manual or Preannotation.

❌

✅

❌

updatedBy.email

The value is an email address.

✅

✅

✅

updatedBy.role

Annotator, QA or Admin.

✅

✅

✅

createdAt

The value is a date with this format: YYYY-MM-DD.

✅

✅

✅

updatedAt

The value is a date with this format: YYYY-MM-DD.

✅

✅

✅

measure.bbox

area, width and height.

❌

✅

❌

🚧

About class names

If the class name contains an operator (and, or, in, not in, contains), the query will handle them as operators, not as words in class names. For example, if the class name is Cars and pedestrians, the query will handle the word cars and the word pedestrians separately. Instead, you can use symbols, such as underscores, to separate the words. So Cars and pedestrians would be changed to cars_and_pedestrians.

Metadata

These parameters can be found under the metadata field.

Parameter

Value

Text

Image

Video

status

NotStarted, InProgress, QualityCheck, Returned, Completed, and Skipped.

✅

✅

✅

approvalStatus

true, false and null.

✅

✅

✅

lastAction.email

The value is an email address.

✅

✅

✅

lastAction.timestamp

The value is a date with this format: YYYY-MM-DD.

❌

✅

✅

width

Numeric value.

❌

✅

✅

height

Numeric value.

❌

✅

✅

name

The value is the item's name.

✅

✅

✅

pinned

true and false.

❌

✅

❌

priority

Numeric value.

✅

✅

✅

Other fields

Field

Parameter

Value

Text

Image

Video

assignment

– email

– isPaused

For the email parameter, the value is an assigned user’s email address. Use none for unassigned items.

For the isPaused parameter, the value is boolean, following the = operator, used to show items whose assigned users’ activity is either paused or active.

You may specify a role before entering either parameter to further narrow down your results, as follows:

assignment.[role_name](isPaused = true)

You may use both parameters within the same query to look for items assigned to a specific user whose activity is paused or not paused, as follows:

assignment(isPaused = true AND email CONTAINS [user_email]

✅

✅

✅

comment

resolved

true and false.

✅

✅

✅

commentCount

–

Numeric value.

✅

✅

✅

tag

–

tag [operator] [tag name]

❌

✅

✅

folderName

–

The value is the folder's name.

✅

✅

✅

folderStatus

–

The value is the folder's status.

✅

✅

✅

subsetName

–

The value is the subset’s name.

✅

✅

✅

freeText

–

freeText [operator] text

✅

❌

❌

random

–

Numeric value.

✅

✅

✅

customMetadata

–

Depending on the field type. Please check this page for more information.

✅

✅

✅

Sort items by query

With the use of the query bar, you can manually specify the data you want to order your item by. You can do so by using orderBy. After typing it in the bar, you must then select one of the following parameters to specify the ordering.

QueryDescriptionImageVideoText
metadata.nameTo order your items by name.✅✅✅
metadata.statusTo order your items by status.✅✅✅
metadata.lastAction.dateTo order your items by the date of the last action taken on an item.✅✅✅
metadata.priorityTo order your items by priority score.✅✅✅
commentCountTo order by number of comments on an item.✅✅✅
InstanceCountTo order the number of instances within an item.✅✅✅
metadata.durationTo order by the duration of videos.❌✅❌

You can read about the functionality of the orderBy query for the Multimodal project type here.

Query example

Say you want to sort the items that haven't been worked on by name, in ascending order. You can use the following query: metadata(status = NotStarted) orderBy metadata.name ASC

Another example is to sort the items that have been marked for Quality Check based on the date of the last action taken, in descending order: metadata(status = QualityCheck) orderBy metadata.lastAction.date DESC

🚧

You can't use orderBy as a sole query

Please note that you can't use the orderBy query on its own (e.g. orderBy metadata.status ASC). Think of it as a secondary attachment to the overall query; it must follow a general query, such as metadata or commentCount, so that you can add an additional parameter to sort your items with.

Generate query

First, make sure that your dataset is synced. You can do so by pressing the Sync data button.

To generate a query:

  1. In the Explore tab, click the query input bar.
  2. Choose the suggested fields and operators or type the query yourself.
  3. To run the query, press Enter on the keyboard.

Save query

To save a query:

  1. Type a query in the query bar.
  2. Click on the star on the right side of the query bar.
  3. In the popup, type a query name.
  4. Check the Save as shared query box to make the query public to users with roles of Project Admin or higher.
  5. Click Save.

📘

The maximum number of characters for a query is 60.
You can save up to 50 queries.

🚧

Only the creator of a shared query can make it private again.

Rename query

To rename a query:

  1. Click on the star in the query bar.
  2. Click the three dots ⋮ next to the query you want to rename.
  3. Select Rename.
  4. Type a new query name.
  5. Click Rename.

Delete query

To delete a query:

  1. Click on the star in the query bar.
  2. Click the three dots ⋮ next to the query you want to delete.
  3. Select Delete.

🚧

Team Owners and Team Admins can delete shared queries regardless of who created them.

Updated about 19 hours ago