Merge branch '20497-updating-wgs-tutorial'
[arvados.git] / 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 and "using collection versioning":../../user/topics/collection-versioning.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 |storage_classes_desired|list|An optional list of storage class names where the blocks should be saved. If not provided, the cluster's default storage class(es) will be set.|@['archival']@|
37 |storage_classes_confirmed|list|Storage classes most recently confirmed by the storage system. This field is an empty list when a collection is first created.|@'archival']@, @[]@|
38 |storage_classes_confirmed_at|datetime|When @storage_classes_confirmed@ was confirmed. If @storage_classes_confirmed@ is @[]@, this field is null.||
39 |trash_at|datetime|If @trash_at@ is non-null and in the past, this collection will be hidden from API calls.  May be untrashed.||
40 |delete_at|datetime|If @delete_at@ is non-null and in the past, the collection may be permanently deleted.||
41 |is_trashed|boolean|True if @trash_at@ is in the past, false if not.||
42 |current_version_uuid|string|UUID of the collection's current version. On new collections, it'll be equal to the @uuid@ attribute.||
43 |version|number|Version number, starting at 1 on new collections. This attribute is read-only.||
44 |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.||
45 |file_count|number|The total number of files in the collection. This attribute is read-only.||
46 |file_size_total|number|The sum of the file sizes in the collection. This attribute is read-only.||
47
48 h3. Conditions of creating a Collection
49
50 If a new @portable_data_hash@ is specified when creating or updating a Collection, it must match the cryptographic digest of the supplied @manifest_text@.
51
52 h3. Side effects of creating a Collection
53
54 Referenced blocks are protected from garbage collection in Keep.
55
56 Data can be shared with other users via the Arvados permission model.
57
58 h2. Methods
59
60 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
61
62 Required arguments are displayed in %{background:#ccffcc}green%.
63
64 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.
65
66 h3. create
67
68 Create a new Collection.
69
70 Arguments:
71
72 table(table table-bordered table-condensed).
73 |_. Argument |_. Type |_. Description |_. Location |_. Example |
74 |collection|object||query||
75 |replace_files|object|Initialize files and directories using content from other collections|query||
76
77 The new collection's content can be initialized by providing a @manifest_text@ key in the provided @collection@ object, or by using the @replace_files@ option (see "replace_files":#replace_files below).
78
79 h3. delete
80
81 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.
82
83 Arguments:
84
85 table(table table-bordered table-condensed).
86 |_. Argument |_. Type |_. Description |_. Location |_. Example |
87 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
88
89 h3. get
90
91 Gets a Collection's metadata by UUID or portable data hash.  When making a request by portable data hash, attributes other than @portable_data_hash@, @manifest_text@, and @trash_at@ are not returned, even when requested explicitly using the @select@ parameter.
92
93 Arguments:
94
95 table(table table-bordered table-condensed).
96 |_. Argument |_. Type |_. Description |_. Location |_. Example |
97 {background:#ccffcc}.|uuid|string|The UUID or portable data hash of the Collection in question.|path||
98
99 h3. list
100
101 List collections.
102
103 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
104
105 table(table table-bordered table-condensed).
106 |_. Argument |_. Type |_. Description |_. Location |_. Example |
107 |include_trash|boolean (default false)|Include trashed collections.|query||
108 |include_old_versions|boolean (default false)|Include past versions of the collection(s) being listed, if any.|query||
109
110 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@.
111
112 h4. Searching Collections for names of file or directories
113
114 You can search collections for specific file or directory names (whole or part) using the following filter in a @list@ query.
115
116 <pre>
117 filters: [["file_names", "ilike", "%sample1234.fastq%"]]
118 </pre>
119
120 Note: @file_names@ is a hidden field used for indexing.  It is not returned by any API call.  On the client, you can programmatically enumerate all the files in a collection using @arv-ls@, the Python SDK @Collection@ class, Go SDK @FileSystem@ struct, the WebDAV API, or the S3-compatible API.
121
122 As of this writing (Arvados 2.4), you can also search for directory paths, but _not_ complete file paths.
123
124 In other words, this will work (when @dir3@ is a directory):
125
126 <pre>
127 filters: [["file_names", "ilike", "%dir1/dir2/dir3%"]]
128 </pre>
129
130 However, this will _not_ return the desired results (where @sample1234.fastq@ is a file):
131
132 <pre>
133 filters: [["file_names", "ilike", "%dir1/dir2/dir3/sample1234.fastq%"]]
134 </pre>
135
136 As a workaround, you can search for both the directory path and file name separately, and then filter on the client side.
137
138 <pre>
139 filters: [["file_names", "ilike", "%dir1/dir2/dir3%"], ["file_names", "ilike", "%sample1234.fastq%"]]
140 </pre>
141
142 h3. update
143
144 Update attributes of an existing Collection.
145
146 Arguments:
147
148 table(table table-bordered table-condensed).
149 |_. Argument |_. Type |_. Description |_. Location |_. Example |
150 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
151 |collection|object||query||
152 |replace_files|object|Delete and replace files and directories using content from other collections|query||
153
154 The collection's content can be updated by providing a @manifest_text@ key in the provided @collection@ object, or by using the @replace_files@ option (see "replace_files":#replace_files below).
155
156 h3. untrash
157
158 Remove a Collection from the trash.  This sets the @trash_at@ and @delete_at@ fields to @null@.
159
160 Arguments:
161
162 table(table table-bordered table-condensed).
163 |_. Argument |_. Type |_. Description |_. Location |_. Example |
164 {background:#ccffcc}.|uuid|string|The UUID of the Collection to untrash.|path||
165 |ensure_unique_name|boolean (default false)|Rename collection uniquely if untrashing it would fail with a unique name conflict.|query||
166
167
168 h3. provenance
169
170 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.
171
172 The general algorithm is:
173
174 # Visit the container request that produced this collection (via @output_uuid@ or @log_uuid@ attributes of the container request)
175 # Visit the input collections to that container request (via @mounts@ and @container_image@ of the container request)
176 # Iterate until there are no more objects to visit
177
178 Arguments:
179
180 table(table table-bordered table-condensed).
181 |_. Argument |_. Type |_. Description |_. Location |_. Example |
182 {background:#ccffcc}.|uuid|string|The UUID of the Collection to get provenance.|path||
183
184 h3. used_by
185
186 Returns a list of objects in the database this collection directly or indirectly contributed to, such as containers that takes this collection as input.
187
188 The general algorithm is:
189
190 # Visit containers that take this collection as input (via @mounts@ or @container_image@ of the container)
191 # Visit collections produced by those containers (via @output@ or @log@ of the container)
192 # Iterate until there are no more objects to visit
193
194 Arguments:
195
196 table(table table-bordered table-condensed).
197 |_. Argument |_. Type |_. Description |_. Location |_. Example |
198 {background:#ccffcc}.|uuid|string|The UUID of the Collection to get usage.|path||
199
200 h2(#replace_files). Using "replace_files" to create/update collections
201
202 The @replace_files@ option can be used with the @create@ and @update@ APIs to efficiently copy individual files and directory trees from other collections, and copy/rename/delete items within an existing collection, without transferring any file data.
203
204 @replace_files@ keys indicate target paths in the new collection, and values specify sources that should be copied to the target paths.
205 * Each target path must be an absolute canonical path beginning with @/@. It must not contain @.@ or @..@ components, consecutive @/@ characters, or a trailing @/@ after the final component.
206 * Each source must be either an empty string (signifying that the target path is to be deleted), or @PDH/path@ where @PDH@ is the portable data hash of a collection on the cluster and @/path@ is a file or directory in that collection.
207 * In an @update@ request, sources may reference the current portable data hash of the collection being updated.
208
209 Example: delete @foo.txt@ from a collection
210
211 <notextile><pre>
212 "replace_files": {
213   "/foo.txt": ""
214 }
215 </pre></notextile>
216
217 Example: rename @foo.txt@ to @bar.txt@ in a collection with portable data hash @fa7aeb5140e2848d39b416daeef4ffc5+45@
218
219 <notextile><pre>
220 "replace_files": {
221   "/foo.txt": "",
222   "/bar.txt": "fa7aeb5140e2848d39b416daeef4ffc5+45/foo.txt"
223 }
224 </pre></notextile>
225
226 Example: delete current contents, then add content from multiple collections
227
228 <notextile><pre>
229 "replace_files": {
230   "/": "",
231   "/copy of collection 1": "1f4b0bc7583c2a7f9102c395f4ffc5e3+45/",
232   "/copy of collection 2": "ea10d51bcf88862dbcc36eb292017dfd+45/"
233 }
234 </pre></notextile>
235
236 Example: replace entire collection with a copy of a subdirectory from another collection
237
238 <notextile><pre>
239 "replace_files": {
240   "/": "1f4b0bc7583c2a7f9102c395f4ffc5e3+45/subdir"
241 }
242 </pre></notextile>
243
244 A target path with a non-empty source cannot be the ancestor of another target path in the same request. For example, the following request is invalid:
245
246 <notextile><pre>
247 "replace_files": {
248   "/foo": "fa7aeb5140e2848d39b416daeef4ffc5+45/",
249   "/foo/this_will_return_an_error": ""
250 }
251 </pre></notextile>