Skip to content

Datasets

create

HTTP Request

POST https://api.solvebio.com/v2/datasets

Parameters

This request does not accept URL parameters.

Authorization

This request requires an authorized user with permission to create new datasets.

Request Body

In the request body, provide a single Dataset resource.

Property Value Description
capacity string The dataset capacity level (small, medium, or large).
vault_id integer The vault version in which to create the dataset.
vault_parent_object_id integer The folder ID in which to create the dataset. Use 'null' to place at '/'.
fields Dataset Fields A list of dataset field objects.
metadata object A dictionary of key/value pairs.
name string The unique name within the vault for this dataset.
tags string A list of strings to organize the dataset.
title string A display name for the dataset.

Response

The response contains a single Dataset resource.

delete

HTTP Request

DELETE https://api.solvebio.com/v2/datasets/{DATASET_ID}

Parameters

This request does not accept URL parameters.

Authorization

This request requires an authorized user with permission to modify the target dataset.

Request Body

Do not supply a request body with this method.

Response

The response returns "HTTP 200 OK" when successful.

get

HTTP Request

GET https://api.solvebio.com/v2/datasets/{DATASET_ID}

Parameters

This request does not accept URL parameters.

Authorization

This request requires an authorized user with permission to view the target dataset.

Request Body

Do not supply a request body with this method.

Response

The response contains a Dataset resource.

query

HTTP Request

POST https://api.solvebio.com/v2/datasets/{DATASET_ID}/data

Parameters

This request does not accept URL parameters.

Authorization

This request requires an authorized user with permission to query the target dataset.

Request Body

The request body should contain valid query parameters:

Property Value Description
filters objects A valid filter object (see below).
facets objects A valid facets object (see below).
fields string A list of fields to include in the results.
exclude_fields string A list of fields to exclude in the results.
ordering string A list of fields to order results by.
query string A valid query string.
limit integer The number of results to return per-page.
offset integer The record offset in the result-set.

Filters & Facets

SolveBio's Python language bindings take care of generating filter syntax automatically.

You can filter datasets on any field using the following filter syntax pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# General pattern
{
    "filters": [
        {
            "{BOOLEAN_OPERATOR}": [
                ["{FIELD}", "{VALUE}"],
                ["{FIELD}__{ACTION}", "{VALUE}"]
            ]
        }
    ]
}

# Example: Simple equality filter
{
    "filters": [
        ["{FIELD}", "{VALUE}"]
    ]
}

# Example: Simple ORed equality filters
{
    "filters": [
        {
            "or": [
                ["{FIELD}", "{VALUE1}"],
                ["{FIELD}", "{VALUE2}"]
            ]
        }
    ]
}

Query filters use a nested syntax, where:

  • {BOOLEAN_OPERATOR} is one of and, or, or not.
  • {FIELD} is a documented field name in the dataset.
  • {ACTION} is a valid field action (see below).
  • {VALUE} can be a string, numeric, or list value.

By default, a {FIELD} with no attached {ACTION} implies the "equal to" operator. Valid actions include:

Action Description
(none) Field is equal to value. If the field's value is a list, this will match values within the list, not the list as a whole.
exact Field is an exact match to value. Useful for longer string and text fields.
in Field is "one of" value, where value is a list. (similar to Python's in operator).
range Field is a number within two within two values. Ranges are inclusive (fully-closed).
gt Field is a number greater than value.
lt Field is a number less than value.
gte Field is a number greater than or equal to value.
lte Field is a number less than or equal to value.
contains Field contains this string value.
regexp Field value matches this regular expression.

Some filter actions (range, gt, lt, gte, lte) may only be used on numeric and date fields.

Full-text fields automatically use the contains filter action instead. The contains filter action acts like a typical search would. Results are automatically ordered by relevance based on your search terms.

See the Querying Data Guide section for more examples.

Response

The dataset query response has the following structure:

Property Value Description
dataset string The name of the dataset.
dataset_id integer The ID of the dataset.
facets objects Facet results (if a facets are requested).
offset integer The current offset within the whole result-set.
results objects A list of dataset records.
took intger Time to retrieve the records, in miliseconds.
total integer The total number of records in the result-set.

batch_query

HTTP Request

POST https://api.solvebio.com/v1/batch_query

Parameters

This request does not accept URL parameters.

Authorization

This request requires an authorized user with permission to query all the datasets provided.

Request Body

The request body should contain a list of one or more dataset queries:

Response

The response contains a list of dataset query responses (see above) with status codes in the same order as specified in the request.