X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/e4f96fc61cd9c85f91bdb0020bc365f2f4825ffb..190b1365c4074d86ae1bb0b9b07c3626a8671fac:/doc/api/methods/collections.html.textile.liquid diff --git a/doc/api/methods/collections.html.textile.liquid b/doc/api/methods/collections.html.textile.liquid index 6f9d142a47..d753f0990f 100644 --- a/doc/api/methods/collections.html.textile.liquid +++ b/doc/api/methods/collections.html.textile.liquid @@ -5,45 +5,66 @@ navmenu: API Methods title: "collections" ... +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} +API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/collections@ -Required arguments are displayed in %{background:#ccffcc}green%. +Object type: @4zz18@ +Example UUID: @zzzzz-4zz18-0123456789abcde@ -h2. create +h2. Resource -Create a new Collection. +Collections describe sets of files in terms of data blocks stored in Keep. See "storage in Keep":{{site.baseurl}}/api/storage.html for details. -Arguments: +Each collection has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html: table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -|collection|object||query|| +|_. Attribute|_. Type|_. Description|_. Example| +|name|string||| +|description|text||| +|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|datetime|True if @trash_at@ is in the past, false if not.|| -h2. delete +h3. Conditions of creating a Collection -Delete an existing 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@. -Arguments: +h3. Side effects of creating a Collection -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path|| +Referenced blocks are protected from garbage collection in Keep. + +Data can be shared with other users via the Arvados permission model. + +h2. Methods + +See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@. + +Required arguments are displayed in %{background:#ccffcc}green%. -h2. destroy +h3. create -destroy collections +Create a new Collection. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| +|collection|object||query|| -h2. get +h3. delete -Gets a Collection's metadata by UUID. +Put a Collection in the trash. This sets the @trash_at@ field to @now@ and @delete_at@ field to @now@ + token TTL. A trashed group is invisible to most API calls unless the @include_trash@ parameter is true. Arguments: @@ -51,48 +72,42 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path|| -h2. index +h3. get -index collections +Gets a Collection's metadata by UUID. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -|order|string||query|| -|where|object||query|| +{background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path|| -h2. list +h3. list List collections. -Arguments: +See "common resource list method.":{{site.baseurl}}/api/methods.html#index -table(table table-bordered table-condensed). -|_. Argument |_. Type |_. Description |_. Location |_. Example | -|limit|integer (default 100)|Maximum number of collections to return.|query|| -|order|string|Order in which to return matching collections.|query|| -|pageToken|string|Page token.|query|| -|q|string|Query string for searching collections.|query|| -|where|object|Conditions for filtering collections.|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@. -h2. show +h3. update -show collections +Update attributes of an existing Collection. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string||path|| +{background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path|| +|collection|object||query|| -h2. update +h3. untrash -Update attributes of an existing Collection. +Remove a Collection from the trash. This sets the @trash_at@ and @delete_at@ fields to @null@. Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -{background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path|| -|collection|object||query|| +{background:#ccffcc}.|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||