Arvados™ Docs
WARNING - you are viewing the documentation for an old version of Arvados. For the latest version, click here.
  1. Concepts
    1. API Reference
    2. API Authorization
    3. REST API syntax
    4. Common resource methods
    5. Common resource fields
  2. Permission and authentication
    1. api_client_authorizations
    2. api_clients
    3. authorized_keys
    4. groups
    5. users
  3. System resources
    1. keep_services
    2. links
    3. logs
    4. nodes
    5. virtual_machines
    6. keep_disks (deprecated)
  4. Data management
    1. collections
    2. repositories
  5. Container engine
    1. container_requests
    2. containers
    3. workflows
  6. Jobs engine (deprecated)
    1. Crunch scripts
    2. jobs
    3. job_tasks
    4. pipeline_instances
    5. pipeline_templates
  7. Metadata for bioinformatics
    1. humans
    2. specimens
    3. traits

collections

API endpoint base: https://pirca.arvadosapi.com/arvados/v1/collections

Object type: 4zz18

Example UUID: zzzzz-4zz18-0123456789abcde

Resource

Collections describe sets of files in terms of data blocks stored in Keep. See storage in Keep for details.

Each collection has, in addition to the Common resource fields:

Attribute Type Description Example
name string
description text
properties hash User-defined metadata, may be used in queries using subproperty filters
portable_data_hash string The MD5 sum of the manifest text stripped of block hints other than the size hint.
manifest_text text
replication_desired number Minimum storage replication level desired for each data block referenced by this collection. A value of null signifies that the site default replication level (typically 2) is desired. 2
replication_confirmed number Replication level most recently confirmed by the storage system. This field is null when a collection is first created, and is reset to null when the manifest_text changes in a way that introduces a new data block. An integer value indicates the replication level of the least replicated data block in the collection. 2, null
replication_confirmed_at datetime When replication_confirmed was confirmed. If replication_confirmed is null, this field is also null.
trash_at datetime If trash_at is non-null and in the past, this collection will be hidden from API calls. May be untrashed.
delete_at datetime If delete_at is non-null and in the past, the collection may be permanently deleted.
is_trashed boolean True if trash_at is in the past, false if not.
current_version_uuid string UUID of the collection’s current version. On new collections, it’ll be equal to the uuid attribute.
version number Version number, starting at 1 on new collections. This attribute is read-only.
preserve_version boolean When set to true on a current version, it will be saved on the next versionable update.
file_count number The total number of files in the collection. This attribute is read-only.
file_size_total number The sum of the file sizes in the collection. This attribute is read-only.

Conditions of creating a Collection

The portable_data_hash and manifest_text attributes must be provided when creating a Collection. The cryptographic digest of the supplied manifest_text must match the supplied portable_data_hash.

Side effects of creating a Collection

Referenced blocks are protected from garbage collection in Keep.

Data can be shared with other users via the Arvados permission model.

Methods

See Common resource methods for more information about create, delete, get, list, and update.

Required arguments are displayed in green.

Supports federated get only, which may be called with either a uuid or a portable data hash. When requesting a portable data hash which is not available on the home cluster, the query is forwarded to all the clusters listed in RemoteClusters and returns the first successful result.

create

Create a new Collection.

Arguments:

Argument Type Description Location Example
collection object query

delete

Put a Collection in the trash. This sets the trash_at field to now and delete_at field to now + token TTL. A trashed collection is invisible to most API calls unless the include_trash parameter is true.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Collection in question. path

get

Gets a Collection’s metadata by UUID or portable data hash. When making a request by portable data hash, the returned record will only have the portable_data_hash and manifest_text.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Collection in question. path

list

List collections.

See common resource list method.

Argument Type Description Location Example
include_trash boolean (default false) Include trashed collections. query
include_old_versions boolean (default false) Include past versions of the collection(s) being listed, if any. query

Note: Because adding access tokens to manifests can be computationally expensive, the manifest_text field is not included in results by default. If you need it, pass a select parameter that includes manifest_text.

update

Update attributes of an existing Collection.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Collection in question. path
collection object query

untrash

Remove a Collection from the trash. This sets the trash_at and delete_at fields to null.

Arguments:

Argument Type Description Location Example
uuid string The UUID of the Collection to untrash. path
ensure_unique_name boolean (default false) Rename collection uniquely if untrashing it would fail with a unique name conflict. query
Previous: keep_disks (deprecated) Next: repositories

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.