# `Arangox.API.Collections`
[🔗](https://github.com/ArangoDB-Community/arangox/blob/v0.8.0/lib/arangox/api/collections.ex#L1)

ArangoDB's Collections operations.

Every function takes the pool as its first argument and returns the decoded
response body. See `Arangox.API.Client` for the options they all accept and
for what a `404` returns.

# `all`

```elixir
@spec all(
  Arangox.conn(),
  keyword()
) :: {:ok, term()} | {:error, Exception.t()}
```

List all collections

Returns basic information for all collections in the current database,
optionally excluding system collections.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "code" => integer,
      "error" => boolean,
      "result" => [%{
        "globallyUniqueId" => string,
        "id" => string,
        "isSystem" => boolean,
        "name" => string,
        "status" => integer,
        "type" => integer
      }]
    }

# `all!`

```elixir
@spec all!(
  Arangox.conn(),
  keyword()
) :: term()
```

List all collections. Raises on error.

See `all/1`.

# `checksum`

```elixir
@spec checksum(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the collection checksum

Calculates a checksum of the meta-data (keys and optionally revision ids) and
optionally the document data in the collection.

The checksum can be used to compare if two collections on different ArangoDB
instances contain the same contents. The current revision of the collection is
returned too so one can make sure the checksums are calculated for the same
state of data.

By default, the checksum is only calculated on the `_key` system attribute
of the documents contained in the collection. For edge collections, the system
attributes `_from` and `_to` are also included in the calculation.

By setting the optional query parameter `withRevisions` to `true`, then revision
IDs (`_rev` system attributes) are included in the checksumming.

By providing the optional query parameter `withData` with a value of `true`,
the user-defined document attributes are included in the calculation, too.

> **INFO:**
Including user-defined attributes will make the checksumming slower.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "checksum" => string,
      "code" => integer,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "isSystem" => boolean,
      "name" => string,
      "revision" => string,
      "status" => integer,
      "type" => integer
    }

# `checksum!`

```elixir
@spec checksum!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the collection checksum. Raises on error.

See `checksum/2`.

# `compact`

```elixir
@spec compact(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Compact a collection

Compacts the data of a collection in order to reclaim disk space.
The operation will compact the document and index data by rewriting the
underlying .sst files and only keeping the relevant entries.

Under normal circumstances, running a compact operation is not necessary, as
the collection data will eventually get compacted anyway. However, in some
situations, e.g. after running lots of update/replace or remove operations,
the disk data for a collection may contain a lot of outdated data for which the
space shall be reclaimed. In this case the compaction operation can be used.

# `compact!`

```elixir
@spec compact!(Arangox.conn(), binary(), keyword()) :: term()
```

Compact a collection. Raises on error.

See `compact/2`.

# `count`

```elixir
@spec count(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the document count of a collection

Get the number of documents in a collection.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "cacheEnabled" => boolean,
      "code" => integer,
      "computedValues" => null,
      "count" => integer,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "internalValidatorType" => integer,
      "isSmartChild" => boolean,
      "isSystem" => boolean,
      "keyOptions" => %{
        "allowUserKeys" => boolean,
        "lastValue" => integer,
        "type" => string
      },
      "name" => string,
      "objectId" => string,
      "schema" => null,
      "status" => integer,
      "statusString" => string,
      "supportsRBAC" => boolean,
      "syncByRevision" => boolean,
      "type" => integer,
      "usesRevisionsAsDocumentIds" => boolean,
      "waitForSync" => boolean,
      "writeConcern" => integer
    }

# `count!`

```elixir
@spec count!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the document count of a collection. Raises on error.

See `count/2`.

# `create`

```elixir
@spec create(Arangox.conn(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Create a collection

Creates a new collection with a given name. The request must contain an
object with the following attributes.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "cacheEnabled" => boolean,
      "code" => integer,
      "computedValues" => null,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "internalValidatorType" => integer,
      "isSmartChild" => boolean,
      "isSystem" => boolean,
      "keyOptions" => %{
        "allowUserKeys" => boolean,
        "lastValue" => integer,
        "type" => string
      },
      "name" => string,
      "objectId" => string,
      "schema" => null,
      "status" => integer,
      "statusString" => string,
      "supportsRBAC" => boolean,
      "syncByRevision" => boolean,
      "type" => integer,
      "usesRevisionsAsDocumentIds" => boolean,
      "waitForSync" => boolean,
      "writeConcern" => integer
    }

# `create!`

```elixir
@spec create!(Arangox.conn(), term(), keyword()) :: term()
```

Create a collection. Raises on error.

See `create/2`.

# `delete`

```elixir
@spec delete(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Drop a collection

Delete the collection identified by `collection-name` and all its documents.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "code" => integer,
      "error" => boolean,
      "id" => string
    }

# `delete!`

```elixir
@spec delete!(Arangox.conn(), binary(), keyword()) :: term()
```

Drop a collection. Raises on error.

See `delete/2`.

# `figures`

```elixir
@spec figures(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the collection statistics

Get the number of documents and additional statistical information
about the collection.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "cacheEnabled" => boolean,
      "code" => integer,
      "computedValues" => null,
      "count" => integer,
      "error" => boolean,
      "figures" => %{
        "cacheInUse" => boolean,
        "cacheSize" => integer,
        "cacheUsage" => integer,
        "documentsSize" => integer,
        "indexes" => %{
          "count" => integer,
          "size" => integer
        }
      },
      "globallyUniqueId" => string,
      "id" => string,
      "internalValidatorType" => integer,
      "isSmartChild" => boolean,
      "isSystem" => boolean,
      "keyOptions" => %{
        "allowUserKeys" => boolean,
        "lastValue" => integer,
        "type" => string
      },
      "name" => string,
      "objectId" => string,
      "schema" => null,
      "status" => integer,
      "statusString" => string,
      "supportsRBAC" => boolean,
      "syncByRevision" => boolean,
      "type" => integer,
      "usesRevisionsAsDocumentIds" => boolean,
      "waitForSync" => boolean,
      "writeConcern" => integer
    }

# `figures!`

```elixir
@spec figures!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the collection statistics. Raises on error.

See `figures/2`.

# `get`

```elixir
@spec get(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the collection information

Returns the basic information about a specific collection.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "code" => integer,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "isSystem" => boolean,
      "name" => string,
      "status" => integer,
      "type" => integer
    }

# `get!`

```elixir
@spec get!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the collection information. Raises on error.

See `get/2`.

# `key_generators`

```elixir
@spec key_generators(
  Arangox.conn(),
  keyword()
) :: {:ok, term()} | {:error, Exception.t()}
```

Get the available key generators

Returns the available key generators for collections.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "keyGenerators" => [string]
    }

# `key_generators!`

```elixir
@spec key_generators!(
  Arangox.conn(),
  keyword()
) :: term()
```

Get the available key generators. Raises on error.

See `key_generators/1`.

# `load`

```elixir
@spec load(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Load a collection

> **WARNING:**
The load function is deprecated from version 3.8.0 onwards and is a no-op
from version 3.9.0 onwards. It should no longer be used and is removed
in ArangoDB v4.0.

Since ArangoDB version 3.9.0 this API does nothing. Previously, it used to
load a collection into memory.

# `load!`

```elixir
@spec load!(Arangox.conn(), binary(), keyword()) :: term()
```

Load a collection. Raises on error.

See `load/2`.

# `load_indexes`

```elixir
@spec load_indexes(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Load collection indexes into memory

You can call this endpoint to try to cache this collection's index entries in
the main memory. Index lookups served from the memory cache can be much faster
than lookups not stored in the cache, resulting in a performance boost.

The endpoint iterates over suitable indexes of the collection and stores the
indexed values (not the entire document data) in memory. This is implemented for
edge indexes only.

The endpoint returns as soon as the index warmup has been scheduled. The index
warmup may still be ongoing in the background, even after the return value has
already been sent. As all suitable indexes are scanned, it may cause significant
I/O activity and background load.

This feature honors memory limits. If the indexes you want to load are smaller
than your memory limit, this feature guarantees that most index values are
cached. If the index is greater than your memory limit, this feature fills
up values up to this limit. You cannot control which indexes of the collection
should have priority over others.

It is guaranteed that the in-memory cache data is consistent with the stored
index data at all times.

# `load_indexes!`

```elixir
@spec load_indexes!(Arangox.conn(), binary(), keyword()) :: term()
```

Load collection indexes into memory. Raises on error.

See `load_indexes/2`.

# `properties`

```elixir
@spec properties(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the properties of a collection

Returns all properties of the specified collection.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "cacheEnabled" => boolean,
      "code" => integer,
      "computedValues" => null,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "internalValidatorType" => integer,
      "isSmartChild" => boolean,
      "isSystem" => boolean,
      "keyOptions" => %{
        "allowUserKeys" => boolean,
        "lastValue" => integer,
        "type" => string
      },
      "name" => string,
      "objectId" => string,
      "schema" => null,
      "status" => integer,
      "statusString" => string,
      "supportsRBAC" => boolean,
      "syncByRevision" => boolean,
      "type" => integer,
      "usesRevisionsAsDocumentIds" => boolean,
      "waitForSync" => boolean,
      "writeConcern" => integer
    }

# `properties!`

```elixir
@spec properties!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the properties of a collection. Raises on error.

See `properties/2`.

# `recalculate_count`

```elixir
@spec recalculate_count(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Recalculate the document count of a collection

Recalculates the document count of a collection, if it ever becomes inconsistent.

# `recalculate_count!`

```elixir
@spec recalculate_count!(Arangox.conn(), binary(), keyword()) :: term()
```

Recalculate the document count of a collection. Raises on error.

See `recalculate_count/2`.

# `rename`

```elixir
@spec rename(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Rename a collection

Renames a collection.

> **INFO:**
Renaming collections is not supported in cluster deployments.

If renaming the collection succeeds, then the collection is also renamed in
all graph definitions inside the `_graphs` collection in the current database.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "code" => integer,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "isSystem" => boolean,
      "name" => string,
      "status" => integer,
      "type" => integer
    }

# `rename!`

```elixir
@spec rename!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Rename a collection. Raises on error.

See `rename/3`.

# `responsible_shard`

```elixir
@spec responsible_shard(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the responsible shard for a document

Returns the ID of the shard that is responsible for the given document
(if the document exists) or that would be responsible if such document
existed.

The request must body must contain a JSON document with at least the
collection's shard key attributes set to some values.

The response is a JSON object with a `shardId` attribute, which will
contain the ID of the responsible shard.

> **INFO:**
This method is only available in cluster deployments on Coordinators.

# `responsible_shard!`

```elixir
@spec responsible_shard!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Get the responsible shard for a document. Raises on error.

See `responsible_shard/3`.

# `revision`

```elixir
@spec revision(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the collection revision ID

The response contains the collection's latest used revision ID.
The revision ID is a server-generated string that clients can use to
check whether data in a collection has changed since the last revision check.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "cacheEnabled" => boolean,
      "code" => integer,
      "computedValues" => null,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "internalValidatorType" => integer,
      "isSmartChild" => boolean,
      "isSystem" => boolean,
      "keyOptions" => %{
        "allowUserKeys" => boolean,
        "lastValue" => integer,
        "type" => string
      },
      "name" => string,
      "objectId" => string,
      "revision" => string,
      "schema" => null,
      "status" => integer,
      "statusString" => string,
      "supportsRBAC" => boolean,
      "syncByRevision" => boolean,
      "type" => integer,
      "usesRevisionsAsDocumentIds" => boolean,
      "waitForSync" => boolean,
      "writeConcern" => integer
    }

# `revision!`

```elixir
@spec revision!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the collection revision ID. Raises on error.

See `revision/2`.

# `shards`

```elixir
@spec shards(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the shard IDs of a collection

The response contains a list of the collection's shard IDs.

If the `details` parameter is set to `true`, it returns an object instead
of a list, with the shard IDs as object attribute keys, and an array with
the responsible servers for each shard mapped to them as attribute values.
The first element of each array is the leader shard.

> **INFO:**
This method is only available in cluster deployments on Coordinators.

## Returns

Recorded against ArangoDB 3.12.10:

    %{...}  # 28 keys, among them "cacheEnabled", "code", "computedValues", "error", "globallyUniqueId", "id", "internalValidatorType", "isDisjoint"

# `shards!`

```elixir
@spec shards!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the shard IDs of a collection. Raises on error.

See `shards/2`.

# `truncate`

```elixir
@spec truncate(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Truncate a collection

Removes all documents from the collection, but leaves the indexes intact.

## Returns

Recorded against ArangoDB 3.12.10:

    %{
      "code" => integer,
      "error" => boolean,
      "globallyUniqueId" => string,
      "id" => string,
      "isSystem" => boolean,
      "name" => string,
      "status" => integer,
      "type" => integer
    }

# `truncate!`

```elixir
@spec truncate!(Arangox.conn(), binary(), keyword()) :: term()
```

Truncate a collection. Raises on error.

See `truncate/2`.

# `unload`

```elixir
@spec unload(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Unload a collection

> **WARNING:**
The unload function is deprecated from version 3.8.0 onwards and is a no-op
from version 3.9.0 onwards. It should no longer be used and is removed
in ArangoDB v4.0.

Since ArangoDB version 3.9.0 this API does nothing. Previously it used to
unload a collection from memory, while preserving all documents.

# `unload!`

```elixir
@spec unload!(Arangox.conn(), binary(), keyword()) :: term()
```

Unload a collection. Raises on error.

See `unload/2`.

# `update_properties`

```elixir
@spec update_properties(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Change the properties of a collection

Changes the properties of a collection. Only the provided attributes are
updated. Collection properties **cannot be changed** once a collection is
created except for the listed properties, as well as the collection name via
the rename endpoint (but not in clusters).

# `update_properties!`

```elixir
@spec update_properties!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Change the properties of a collection. Raises on error.

See `update_properties/3`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*