# Examples

# Authentication

A access tokens can be created in the user settings (opens new window).

$ datatorch login
from datatorch.api import ApiClient

# Use global access token set by CLI
api = ApiClient()

# Specify an already existing token
api = ApiClient(api_key='API_TOKEN')

# Custom DataTorch instance
api = ApiClient(api_url='http://example.com/api')

Alternatively a user can set the global access token environment variables DATATORCH_API_KEY

# Execute Raw GraphQL

Building your own GraphQL queries provides you with the ability to return data you need by querying the server once in the most efficient way. Thus using raw GraphQL queries is the preferred method for interaction with the DataTorch API.

Checkout the GraphQL playground (opens new window) for an interactive GraphQL client along with documentation. Users may have to set the address to https://datatorch.io/api/graphql for it to work correctly.

from datatorch.api import ApiClient

api = ApiClient()

# Create RAW GraphQL
QUERY = '''
    query GetFile($id: ID!) {
      file(id: $id) {
        link {
raw = api.execute(QUERY, params={'id': file_id})
# Execute GraphQL files
raw = api.execute_file('dir/to/file.gql', params={'id': file_id})

# Manipulating Files

Depending on the information you know about the file will depend on the method you use for retrieval.

from datatorch.api import ApiClient, Annotation, BoundingBox

anno = Annotation()
anno.add(BoundingBox.create(10, 10, 50, 50))

your_file = ApiClient().file(file_id)

anno2 = anno.copy()

Objects will only be inserted once they have been attached to an object that already exists on the server.

# Advanced Filtering

In this example we will look at using Where filtering object to create complex queries for retrieving files.

Parameters passed into the Where constructor start with an property followed by two underscores and then an operator.

Operator Types Description
equal boolean, number, string Equals (=) [default operation]
not_equal boolean, number, string Not Equals (!=)
gt number, string Greater than (>)
gte number, string Greater than or Equal (>=)
lt number, string Less than (<)
lte number, string Less than or Equal (<=)
in List[number, string] In an array
starts_with string Starts with
ends_with string Ends with
contains string Contains
like string SQL Like string

Information about the available properties for each entity can be found by viewing the GraphQL documentation (note: variables are in snake case).

The where clause in the example below will return:

  • files that are PNG's and,
  • the file path starts with example/path and,
  • the file is a child of the storage provider named aws-storage
from datatorch.api import ApiClient, Where

client = ApiClient()

file_where = Where(

files = client.files(where=file_where)