doc/api/methods/collections.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "collections"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/collections@
  15
  16 Object type: @4zz18@
  17
  18 Example UUID: @zzzzz-4zz18-0123456789abcde@
  19
  20 h2. Resource
  21
  22 Collections describe sets of files in terms of data blocks stored in Keep.  See "Keep - Content-Addressable Storage":{{site.baseurl}}/architecture/storage.html for details.
  23
  24 Each collection has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  25
  26 table(table table-bordered table-condensed).
  27 |_. Attribute|_. Type|_. Description|_. Example|
  28 |name|string|||
  29 |description|text|||
  30 |properties|hash|User-defined metadata, may be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters ||
  31 |portable_data_hash|string|The MD5 sum of the manifest text stripped of block hints other than the size hint.||
  32 |manifest_text|text|||
  33 |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@|
  34 |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|
  35 |replication_confirmed_at|datetime|When replication_confirmed was confirmed. If replication_confirmed is null, this field is also null.||
  36 |trash_at|datetime|If @trash_at@ is non-null and in the past, this collection will be hidden from API calls.  May be untrashed.||
  37 |delete_at|datetime|If @delete_at@ is non-null and in the past, the collection may be permanently deleted.||
  38 |is_trashed|boolean|True if @trash_at@ is in the past, false if not.||
  39 |current_version_uuid|string|UUID of the collection's current version. On new collections, it'll be equal to the @uuid@ attribute.||
  40 |version|number|Version number, starting at 1 on new collections. This attribute is read-only.||
  41 |preserve_version|boolean|When set to true on a current version, it will be persisted. When passing @true@ as part of a bigger update call, both current and newly created versions are persisted.||
  42 |file_count|number|The total number of files in the collection. This attribute is read-only.||
  43 |file_size_total|number|The sum of the file sizes in the collection. This attribute is read-only.||
  44
  45 h3. Conditions of creating a Collection
  46
  47 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@.
  48
  49 h3. Side effects of creating a Collection
  50
  51 Referenced blocks are protected from garbage collection in Keep.
  52
  53 Data can be shared with other users via the Arvados permission model.
  54
  55 h2. Methods
  56
  57 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  58
  59 Required arguments are displayed in %{background:#ccffcc}green%.
  60
  61 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.
  62
  63 h3. create
  64
  65 Create a new Collection.
  66
  67 Arguments:
  68
  69 table(table table-bordered table-condensed).
  70 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  71 |collection|object||query||
  72
  73 h3. delete
  74
  75 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.
  76
  77 Arguments:
  78
  79 table(table table-bordered table-condensed).
  80 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  81 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
  82
  83 h3. get
  84
  85 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@.
  86
  87 Arguments:
  88
  89 table(table table-bordered table-condensed).
  90 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  91 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
  92
  93 h3. list
  94
  95 List collections.
  96
  97 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  98
  99 table(table table-bordered table-condensed).
 100 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 101 |include_trash|boolean (default false)|Include trashed collections.|query||
 102 |include_old_versions|boolean (default false)|Include past versions of the collection(s) being listed, if any.|query||
 103
 104 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@.
 105
 106 h3. update
 107
 108 Update attributes of an existing Collection.
 109
 110 Arguments:
 111
 112 table(table table-bordered table-condensed).
 113 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 114 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
 115 |collection|object||query||
 116
 117 h3. untrash
 118
 119 Remove a Collection from the trash.  This sets the @trash_at@ and @delete_at@ fields to @null@.
 120
 121 Arguments:
 122
 123 table(table table-bordered table-condensed).
 124 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 125 {background:#ccffcc}.|uuid|string|The UUID of the Collection to untrash.|path||
 126 |ensure_unique_name|boolean (default false)|Rename collection uniquely if untrashing it would fail with a unique name conflict.|query||
 127
 128
 129 h3. provenance
 130
 131 Returns a list of objects in the database that directly or indirectly contributed to producing this collection, such as the container request that produced this collection as output.
 132
 133 The general algorithm is:
 134
 135 # Visit the container request that produced this collection (via @output_uuid@ or @log_uuid@ attributes of the container request)
 136 # Visit the input collections to that container request (via @mounts@ and @container_image@ of the container request)
 137 # Iterate until there are no more objects to visit
 138
 139 Arguments:
 140
 141 table(table table-bordered table-condensed).
 142 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 143 {background:#ccffcc}.|uuid|string|The UUID of the Collection to get provenance.|path||
 144
 145 h3. used_by
 146
 147 Returns a list of objects in the database this collection directly or indirectly contributed to, such as containers that takes this collection as input.
 148
 149 The general algorithm is:
 150
 151 # Visit containers that take this collection as input (via @mounts@ or @container_image@ of the container)
 152 # Visit collections produced by those containers (via @output@ or @log@ of the container)
 153 # Iterate until there are no more objects to visit
 154
 155 Arguments:
 156
 157 table(table table-bordered table-condensed).
 158 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 159 {background:#ccffcc}.|uuid|string|The UUID of the Collection to get usage.|path||