Fetching Objects

Updated 2 weeks ago by Florijan Stamenkovic

Top-level Objects


Top-level objects such as Projects and Datasets are fetched using methods of the Client object.

>>> from labelbox import Client
>>> client = Client()
>>> projects = client.get_projects()
>>> type(projects)

Note that the object returned for methods returning multiple objects (such as get_projects() ) is of the PaginatedCollection type. It transparently handles paged fetching for you. For more info consult General Concepts.

Lookup On ID

You can get a single, specific top-level object by providing a unique ID of that object.

>>> dataset = client.get_dataset("cjzxrdns52e5u0a46ne79f2qn")
>>> type(dataset)

Single-object fetches are performed immediately. If there is no object of the type you seek with a unique ID you provide, a ResourceNotFoundError will be raised.

Current User

Each request you make to the server is attributed to you based on the API key you provide to the Python client API. Based on that key, the User object representing you in the database can be obtained.

>>> me = client.get_user()


Relationships are resolved by calling the appropriate method on a source object. For example, to get all the Datasets a specific Project is related to:

>>> datasets = project.datasets()
>>> type(datasets)

For To-Many relationships a PaginatedCollection is returned. For To-One relationships the actual object is returned.

>>> my_organization = client.get_user().organization()



You can filter top-level object collections and To-Many relationships by providing a where clause. The syntax for defining a comparison is: <field> <comparison_operator> <value>. Such a comparison can be passed under the where parameter of a top-level collection fetch or a To-Many relationship expansion.

>>> from labelbox import Project
>>> projects_named_x = client.get_projects(where=Project.name == "X")

Standard comparison operators (==, !=, >, >=, <, <=) are supported.

Logical Expressions

Comparisons can also be combined using logical expressions. You can use the Python bitwise operators &, | and ~ (currently only & is supported) to combine comparisons and expressions into new expressions. Note that due to operator precedence you need to use parentheses when writing logical expressions.

>>> projects = client.get_projects(where=(Project.name == "X") & (Project.description == "Y"))


To-Many relationship fetches can be sorted by providing an argument for the order_by parameter of the relationship method.

>>> sorted_datasets = project.datasets(order_by=Dataset.name.asc)

You can sort on only one field, in an ascending or descending way.

Currently it's not possible to sort top-level collections (such as client.get_projects()) in a fetch. You can of course do it on the client side.

How did we do?