DocumentCollection | arangojs

Represents an document collection in a Database.

See EdgeCollection for a variant of this interface more suited for edge collections.

When using TypeScript, collections can be cast to a specific document data type to increase type safety.

example

interface Person {
  name: string;
}
const db = new Database();
const documents = db.collection("persons") as DocumentCollection<Person>;

Type parameters

T: Record<string, unknown> = any

Type to use for document data. Defaults to any.

Hierarchy

ArangoCollection
- DocumentCollection
  - EdgeCollection

Index

Properties

Methods

Properties

Readonly isArangoCollection

isArangoCollection: true

internal: Indicates that this object represents an ArangoDB collection.

Readonly name

name: string

Name of the collection.

Methods

all

all(options?: SimpleQueryAllOptions): Promise<ArrayCursor<Document<T>>>

Retrieves all documents in the collection.
deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example
```
const db = new Database();
const collection = db.collection("some-collection");
// const cursor = await collection.all();
const cursor = await db.query(aql`
  FOR doc IN ${collection}
  RETURN doc
`);
```
Parameters
- Optional options: SimpleQueryAllOptions
  
  Options for retrieving the documents.
Returns Promise<ArrayCursor<Document<T>>>

any

any(): Promise<Document<T>>

Retrieves a random document from the collection.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
// const doc = await collection.any();
const cursor = await db.query(aql`
  FOR doc IN ${collection}
  SORT RAND()
  LIMIT 1
  RETURN doc
`);
const doc = await cursor.next();

Returns Promise<Document<T>>

byExample

byExample(example: Partial<DocumentData<T>>, options?: SimpleQueryByExampleOptions): Promise<ArrayCursor<Document<T>>>

Retrieves all documents in the collection matching the given example.
deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example
```
const db = new Database();
const collection = db.collection("some-collection");
// const cursor = await collection.byExample({ flavor: "strawberry" });
const cursor = await db.query(aql`
  FOR doc IN ${collection}
  FILTER doc.flavor == "strawberry"
  RETURN doc
`);
```
Parameters
- example: Partial<DocumentData<T>>
  
  An object representing an example for documents.
- Optional options: SimpleQueryByExampleOptions
  
  Options for retrieving the documents.
Returns Promise<ArrayCursor<Document<T>>>

checksum

checksum(options?: CollectionChecksumOptions): Promise<ArangoResponseMetadata & CollectionMetadata & { checksum: string; revision: string }>

Retrieves the collection checksum.
example
```
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.checksum();
// data contains the collection's checksum
```
Parameters
- Optional options: CollectionChecksumOptions
  
  Options for retrieving the checksum.
Returns Promise<ArangoResponseMetadata & CollectionMetadata & { checksum: string; revision: string }>

count

count(): Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { count: number }>

Retrieves information about the number of documents in a collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.count();
// data contains the collection's count

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { count: number }>

create

create(options?: CreateCollectionOptions & { type?: DOCUMENT_COLLECTION | EDGE_COLLECTION }): Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

Creates a collection with the given options and the instance's name.

Note: When called on an EdgeCollection instance in TypeScript, the type option must still be set to the correct CollectionType. Otherwise this will result in the collection being created with the default type (i.e. as a document collection).

example

const db = new Database();
const collection = db.collection("potatoes");
await collection.create();
// the document collection "potatoes" now exists

example

const db = new Database();
const collection = db.collection("friends");
await collection.create({ type: CollectionType.EDGE_COLLECTION });
// the edge collection "friends" now exists

example

interface Friend {
  startDate: number;
  endDate?: number;
}
const db = new Database();
const collection = db.collection("friends") as EdgeCollection<Friend>;
// even in TypeScript you still need to indicate the collection type
// if you want to create an edge collection
await collection.create({ type: CollectionType.EDGE_COLLECTION });
// the edge collection "friends" now exists

Parameters

Optional options: CreateCollectionOptions & { type?: DOCUMENT_COLLECTION | EDGE_COLLECTION }

Options for creating the collection.

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

document

document(selector: DocumentSelector, options?: CollectionReadOptions): Promise<Document<T>>
document(selector: DocumentSelector, graceful: boolean): Promise<Document<T>>

Retrieves the document matching the given key or id.

Throws an exception when passed a document or _id from a different collection.

example

const db = new Database();
const collection = db.collection("some-collection");
try {
  const document = await collection.document("abc123");
  console.log(document);
} catch (e) {
  console.error("Could not find document");
}

example

const db = new Database();
const collection = db.collection("some-collection");
const document = await collection.document("abc123", { graceful: true });
if (document) {
  console.log(document);
} else {
  console.error("Could not find document");
}

Parameters

selector: DocumentSelector

Document _key, _id or object with either of those properties (e.g. a document from this collection).
Optional options: CollectionReadOptions

Options for retrieving the document.

Returns Promise<Document<T>>

Retrieves the document matching the given key or id.

Throws an exception when passed a document or _id from a different collection.

example

const db = new Database();
const collection = db.collection("some-collection");
try {
  const document = await collection.document("abc123", false);
  console.log(document);
} catch (e) {
  console.error("Could not find document");
}

example

const db = new Database();
const collection = db.collection("some-collection");
const document = await collection.document("abc123", true);
if (document) {
  console.log(document);
} else {
  console.error("Could not find document");
}

Parameters

selector: DocumentSelector

Document _key, _id or object with either of those properties (e.g. a document from this collection).
graceful: boolean

If set to true, null is returned instead of an exception being thrown if the document does not exist.

Returns Promise<Document<T>>

documentExists

documentExists(selector: DocumentSelector): Promise<boolean>

Checks whether a document matching the given key or id exists in this collection.

Throws an exception when passed a document or _id from a different collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
const exists = await collection.documentExists("abc123");
if (!exists) {
  console.log("Document does not exist");
}
```
Parameters
- selector: DocumentSelector
  
  Document _key, _id or object with either of those properties (e.g. a document from this collection).
Returns Promise<boolean>

documentId

documentId(selector: DocumentSelector): string

Derives a document _id from the given selector for this collection.

Throws an exception when passed a document or _id from a different collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const meta = await collection.save({ foo: "bar" }, { returnNew: true });
const doc = meta.new;
console.log(collection.documentId(meta)); // via meta._id
console.log(collection.documentId(doc)); // via doc._id
console.log(collection.documentId(meta._key)); // also works

example

const db = new Database();
const collection1 = db.collection("some-collection");
const collection2 = db.collection("other-collection");
const meta = await collection1.save({ foo: "bar" });
// Mixing collections is usually a mistake
console.log(collection1.documentId(meta)); // ok: same collection
console.log(collection2.documentId(meta)); // throws: wrong collection
console.log(collection2.documentId(meta._id)); // also throws
console.log(collection2.documentId(meta._key)); // ok but wrong collection

Parameters

selector: DocumentSelector

Document _key, _id or object with either of those properties (e.g. a document from this collection).

Returns string

documents

documents(selectors: (string | ObjectWithKey)[], options?: CollectionBatchReadOptions): Promise<Document<T>[]>

Retrieves the documents matching the given key or id values.

Throws an exception when passed a document or _id from a different collection, or if the document does not exist.
example
```
const db = new Database();
const collection = db.collection("some-collection");
try {
  const documents = await collection.documents(["abc123", "xyz456"]);
  console.log(documents);
} catch (e) {
  console.error("Could not find document");
}
```
Parameters
- selectors: (string | ObjectWithKey)[]
  
  Array of document _key, _id or objects with either of those properties (e.g. a document from this collection).
- Optional options: CollectionBatchReadOptions
  
  Options for retrieving the documents.
Returns Promise<Document<T>[]>

drop

drop(options?: CollectionDropOptions): Promise<ArangoResponseMetadata>

Deletes the collection from the database.

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.drop();
// The collection "some-collection" is now an ex-collection

Parameters

Optional options: CollectionDropOptions

Options for dropping the collection.

Returns Promise<ArangoResponseMetadata>

dropIndex

dropIndex(selector: IndexSelector): Promise<ArangoResponseMetadata & { id: string }>

Deletes the index with the given name or id from the database.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.dropIndex("some-index");
// The index "some-index" no longer exists
```
Parameters
- selector: IndexSelector
  
  Index name, id or object with either property.
Returns Promise<ArangoResponseMetadata & { id: string }>

ensureIndex

ensureIndex(details: EnsurePersistentIndexOptions): Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; type: "persistent" } & { isNewlyCreated: boolean }>
ensureIndex(details: EnsureHashIndexOptions): Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; selectivityEstimate: number; type: "hash" } & { isNewlyCreated: boolean }>
ensureIndex(details: EnsureSkiplistIndexOptions): Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; type: "skiplist" } & { isNewlyCreated: boolean }>
ensureIndex(details: EnsureTtlIndexOptions): Promise<ArangoResponseMetadata & GenericIndex & { expireAfter: number; fields: [string]; selectivityEstimate: number; type: "ttl" } & { isNewlyCreated: boolean }>
ensureIndex(details: EnsureFulltextIndexOptions): Promise<ArangoResponseMetadata & GenericIndex & { fields: [string]; minLength: number; type: "fulltext" } & { isNewlyCreated: boolean }>
ensureIndex(details: EnsureGeoIndexOptions): Promise<ArangoResponseMetadata & GenericIndex & { bestIndexedLevel: number; fields: [string] | [string, string]; geoJson: boolean; maxNumCoverCells: number; type: "geo"; worstIndexedLevel: number } & { isNewlyCreated: boolean }>

Creates a persistent index on the collection if it does not already exist.

example

const db = new Database();
const collection = db.collection("some-collection");
// Create a unique index for looking up documents by username
await collection.ensureIndex({
  type: "persistent",
  fields: ["username"],
  name: "unique-usernames",
  unique: true
});

Parameters

details: EnsurePersistentIndexOptions

Options for creating the persistent index.

Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; type: "persistent" } & { isNewlyCreated: boolean }>

Creates a hash index on the collection if it does not already exist.

When using the RocksDB storage engine, hash indexes behave identically to persistent indexes.
example
```
const db = new Database();
const collection = db.collection("some-collection");
// Create a unique index for looking up documents by username
await collection.ensureIndex({
  type: "hash",
  fields: ["username"],
  name: "unique-usernames",
  unique: true
});
```
Parameters
- details: EnsureHashIndexOptions
  
  Options for creating the hash index.
Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; selectivityEstimate: number; type: "hash" } & { isNewlyCreated: boolean }>
Creates a skiplist index on the collection if it does not already exist.

When using the RocksDB storage engine, skiplist indexes behave identically to persistent indexes.
example
```
const db = new Database();
const collection = db.collection("some-collection");
// Create an index for sorting email addresses
await collection.ensureIndex({
  type: "skiplist",
  fields: ["email"]
});
```
Parameters
- details: EnsureSkiplistIndexOptions
  
  Options for creating the skiplist index.
Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; type: "skiplist" } & { isNewlyCreated: boolean }>

Creates a TTL index on the collection if it does not already exist.

example

const db = new Database();
const collection = db.collection("some-collection");
// Expire documents with "createdAt" timestamp one day after creation
await collection.ensureIndex({
  type: "ttl",
  fields: ["createdAt"],
  expireAfter: 60 * 60 * 24 // 24 hours
});

example

const db = new Database();
const collection = db.collection("some-collection");
// Expire documents with "expiresAt" timestamp according to their value
await collection.ensureIndex({
  type: "ttl",
  fields: ["expiresAt"],
  expireAfter: 0 // when attribute value is exceeded
});

Parameters

details: EnsureTtlIndexOptions

Options for creating the TTL index.

Returns Promise<ArangoResponseMetadata & GenericIndex & { expireAfter: number; fields: [string]; selectivityEstimate: number; type: "ttl" } & { isNewlyCreated: boolean }>

Creates a fulltext index on the collection if it does not already exist.
example
```
const db = new Database();
const collection = db.collection("some-collection");
// Create a fulltext index for tokens longer than or equal to 3 characters
await collection.ensureIndex({
  type: "fulltext",
  fields: ["description"],
  minLength: 3
});
```
Parameters
- details: EnsureFulltextIndexOptions
  
  Options for creating the fulltext index.
Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: [string]; minLength: number; type: "fulltext" } & { isNewlyCreated: boolean }>
Creates a geo index on the collection if it does not already exist.
example
```
const db = new Database();
const collection = db.collection("some-collection");
// Create an index for GeoJSON data
await collection.ensureIndex({
  type: "geo",
  fields: ["lngLat"],
  geoJson: true
});
```
Parameters
- details: EnsureGeoIndexOptions
  
  Options for creating the geo index.
Returns Promise<ArangoResponseMetadata & GenericIndex & { bestIndexedLevel: number; fields: [string] | [string, string]; geoJson: boolean; maxNumCoverCells: number; type: "geo"; worstIndexedLevel: number } & { isNewlyCreated: boolean }>

exists

exists(): Promise<boolean>

Checks whether the collection exists.

example

const db = new Database();
const collection = db.collection("some-collection");
const result = await collection.exists();
// result indicates whether the collection exists

Returns Promise<boolean>

figures

figures(details?: boolean): Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { count: number; figures: Dict<any> }>

Retrieves statistics for a collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.figures();
// data contains the collection's figures
```
Parameters
- Optional details: boolean
  
  whether to return extended storage engine-specific details to the figures, which may cause additional load and impact performance
Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { count: number; figures: Dict<any> }>

firstExample

firstExample(example: Partial<DocumentData<T>>): Promise<Document<T>>

Retrieves a single document in the collection matching the given example.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
// const doc = await collection.firstExample({ flavor: "strawberry" });
const cursor = await db.query(aql`
  FOR doc IN ${collection}
  FILTER doc.flavor == "strawberry"
  LIMIT 1
  RETURN doc
`);
const doc = await cursor.next();

Parameters

example: Partial<DocumentData<T>>

An object representing an example for the document.

Returns Promise<Document<T>>

fulltext

fulltext(attribute: string, query: string, options?: SimpleQueryFulltextOptions): Promise<ArrayCursor<Document<T>>>

Performs a fulltext query in the given attribute on the collection.
deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example
```
const db = new Database();
const collection = db.collection("some-collection");
// const cursor = await collection.fulltext("article", "needle");
const cursor = await db.query(aql`
  FOR doc IN FULLTEXT(${collection}, "article", "needle")
  RETURN doc
`);
```
Parameters
- attribute: string
  
  Name of the field to search.
- query: string
  
  Fulltext query string to search for.
- Optional options: SimpleQueryFulltextOptions
  
  Options for performing the fulltext query.
Returns Promise<ArrayCursor<Document<T>>>

get

get(): Promise<ArangoResponseMetadata & CollectionMetadata>

Retrieves general information about the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.get();
// data contains general information about the collection

Returns Promise<ArangoResponseMetadata & CollectionMetadata>

getResponsibleShard

getResponsibleShard(document: Partial<Document<T>>): Promise<string>

Retrieves the shardId of the shard responsible for the given document.
example
```
const db = new Database();
const collection = db.collection("some-collection");
const responsibleShard = await collection.getResponsibleShard();
```
Parameters
- document: Partial<Document<T>>
  
  Document in the collection to look up the shardId of.
Returns Promise<string>

import

import(data: DocumentData<T>[], options?: CollectionImportOptions): Promise<CollectionImportResult>
import(data: any[][], options?: CollectionImportOptions): Promise<CollectionImportResult>
import(data: string | Buffer | Blob, options?: CollectionImportOptions & { type?: "documents" | "list" | "auto" }): Promise<CollectionImportResult>

Bulk imports the given data into the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
  [
    { _key: "jcd", password: "bionicman" },
    { _key: "jreyes", password: "amigo" },
    { _key: "ghermann", password: "zeitgeist" }
  ]
);

Parameters

data: DocumentData<T>[]

The data to import, as an array of document data.
Optional options: CollectionImportOptions

Options for importing the data.

Returns Promise<CollectionImportResult>

Bulk imports the given data into the collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
  [
    [ "_key", "password" ],
    [ "jcd", "bionicman" ],
    [ "jreyes", "amigo" ],
    [ "ghermann", "zeitgeist" ]
  ]
);
```
Parameters
- data: any[][]
  
  The data to import, as an array containing a single array of attribute names followed by one or more arrays of attribute values for each document.
- Optional options: CollectionImportOptions
  
  Options for importing the data.
Returns Promise<CollectionImportResult>

Bulk imports the given data into the collection.

If type is omitted, data must contain one JSON array per line with the first array providing the attribute names and all other arrays providing attribute values for each document.

If type is set to "documents", data must contain one JSON document per line.

If type is set to "list", data must contain a JSON array of documents.

If type is set to "auto", data can be in either of the formats supported by "documents" or "list".

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
  '{"_key":"jcd","password":"bionicman"}\r\n' +
  '{"_key":"jreyes","password":"amigo"}\r\n' +
  '{"_key":"ghermann","password":"zeitgeist"}\r\n',
  { type: "documents" } // or "auto"
);

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
  '[{"_key":"jcd","password":"bionicman"},' +
  '{"_key":"jreyes","password":"amigo"},' +
  '{"_key":"ghermann","password":"zeitgeist"}]',
  { type: "list" } // or "auto"
);

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
  '["_key","password"]\r\n' +
  '["jcd","bionicman"]\r\n' +
  '["jreyes","amigo"]\r\n' +
  '["ghermann","zeitgeist"]\r\n'
);

Parameters

data: string | Buffer | Blob

The data to import as a Buffer (Node), Blob (browser) or string.
Optional options: CollectionImportOptions & { type?: "documents" | "list" | "auto" }

Options for importing the data.

Returns Promise<CollectionImportResult>

index

index(selector: IndexSelector): Promise<Index>

Returns an index description by name or id if it exists.
example
```
const db = new Database();
const collection = db.collection("some-collection");
const index = await collection.index("some-index");
```
Parameters
- selector: IndexSelector
  
  Index name, id or object with either property.
Returns Promise<Index>

indexes

indexes(): Promise<Index[]>

Returns a list of all index descriptions for the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const indexes = await collection.indexes();

Returns Promise<Index[]>

list

list(type?: "id" | "key" | "path"): Promise<ArrayCursor<string>>

Retrieves a list of references for all documents in the collection.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
// const ids = await collection.list("id");
const ids = await db.query(aql`
  FOR doc IN ${collection}
  RETURN doc._id
`);

example

const db = new Database();
const collection = db.collection("some-collection");
// const keys = await collection.list("key");
const keys = await db.query(aql`
  FOR doc IN ${collection}
  RETURN doc._key
`);

example

const db = new Database();
const collection = db.collection("some-collection");
// const paths = await collection.list("path");
const paths = await db.query(aql`
  FOR doc IN ${collection}
  RETURN CONCAT("/_db/", CURRENT_DATABASE(), "/_api/document/", doc._id)
`);

Parameters

Optional type: "id" | "key" | "path"

The type of document reference to retrieve.

Returns Promise<ArrayCursor<string>>

load

load(count?: true): Promise<ArangoResponseMetadata & CollectionMetadata & { count: number }>
load(count: false): Promise<ArangoResponseMetadata & CollectionMetadata>

Instructs ArangoDB to load the collection into memory.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.load();
// the collection has now been loaded into memory
```
Parameters
- Optional count: true
  
  Whether the number of documents in the collection should be included in the server response. Disabling this may speed up this process in future versions of ArangoDB.
Returns Promise<ArangoResponseMetadata & CollectionMetadata & { count: number }>
Instructs ArangoDB to load the collection into memory.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.load(false);
// the collection has now been loaded into memory
```
Parameters
- count: false
  
  Whether the number of documents in the collection should be included in the server response. Disabling this may speed up this process in future versions of ArangoDB.
Returns Promise<ArangoResponseMetadata & CollectionMetadata>

loadIndexes

loadIndexes(): Promise<boolean>

(RocksDB only.) Instructs ArangoDB to load as many indexes of the collection into memory as permitted by the memory limit.

example

const db = new Database();
const collection = db.collection("indexed-collection");
await collection.loadIndexes();
// the indexes are now loaded into memory

Returns Promise<boolean>

lookupByKeys

lookupByKeys(keys: string[]): Promise<Document<T>[]>

Retrieves all documents matching the given document keys.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
const keys = ["a", "b", "c"];
// const docs = await collection.byKeys(keys);
const cursor = await db.query(aql`
  FOR key IN ${keys}
  LET doc = DOCUMENT(${collection}, key)
  RETURN doc
`);
const docs = await cursor.all();

Parameters

keys: string[]

An array of document keys to look up.

Returns Promise<Document<T>[]>

properties

properties(): Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>
properties(properties: CollectionPropertiesOptions): Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

Retrieves the collection's properties.

example

const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.properties();
// data contains the collection's properties

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

Replaces the properties of the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const result = await collection.setProperties({ waitForSync: true });
// the collection will now wait for data being written to disk
// whenever a document is changed

Parameters

properties: CollectionPropertiesOptions

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

recalculateCount

recalculateCount(): Promise<boolean>

(RocksDB only.) Instructs ArangoDB to recalculate the collection's document count to fix any inconsistencies.

example

const db = new Database();
const collection = db.collection("inconsistent-collection");
const badData = await collection.count();
// oh no, the collection count looks wrong -- fix it!
await collection.recalculateCount();
const goodData = await collection.count();
// goodData contains the collection's improved count

Returns Promise<boolean>

remove

remove(selector: DocumentSelector, options?: CollectionRemoveOptions): Promise<DocumentMetadata & { old?: Document<T> }>

Removes an existing document from the collection.

Throws an exception when passed a document or _id from a different collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.remove("abc123");
// document with key "abc123" deleted
```
example
```
const db = new Database();
const collection = db.collection("some-collection");
const doc = await collection.document("abc123");
await collection.remove(doc);
// document with key "abc123" deleted
```
Parameters
- selector: DocumentSelector
  
  Document _key, _id or object with either of those properties (e.g. a document from this collection).
- Optional options: CollectionRemoveOptions
  
  Options for removing the document.
Returns Promise<DocumentMetadata & { old?: Document<T> }>

removeAll

removeAll(selectors: DocumentSelector[], options?: CollectionRemoveOptions): Promise<(DocumentMetadata & { old?: Document<T> })[]>

Removes existing documents from the collection.

Throws an exception when passed any document or _id from a different collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.removeAll(["abc123", "def456"]);
// document with keys "abc123" and "def456" deleted
```
Parameters
- selectors: DocumentSelector[]
  
  Documents _key, _id or objects with either of those properties (e.g. documents from this collection).
- Optional options: CollectionRemoveOptions
  
  Options for removing the documents.
Returns Promise<(DocumentMetadata & { old?: Document<T> })[]>

removeByExample

removeByExample(example: Partial<DocumentData<T>>, options?: SimpleQueryRemoveByExampleOptions): Promise<ArangoResponseMetadata & SimpleQueryRemoveByExampleResult>

Removes all documents in the collection matching the given example.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
// const { deleted } = await collection.removeByExample({
//   flavor: "strawberry"
// });
const cursor = await db.query(aql`
  RETURN LENGTH(
    FOR doc IN ${collection}
    FILTER doc.flavor == "strawberry"
    REMOVE doc IN ${collection}
    RETURN 1
  )
`);
const deleted = await cursor.next();

Parameters

example: Partial<DocumentData<T>>

An object representing an example for the document.
Optional options: SimpleQueryRemoveByExampleOptions

Options for removing the documents.

Returns Promise<ArangoResponseMetadata & SimpleQueryRemoveByExampleResult>

removeByKeys

removeByKeys(keys: string[], options?: SimpleQueryRemoveByKeysOptions): Promise<ArangoResponseMetadata & SimpleQueryRemoveByKeysResult<T>>

Removes all documents matching the given document keys.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
const keys = ["a", "b", "c"];
// const { removed, ignored } = await collection.removeByKeys(keys);
const cursor = await db.query(aql`
  FOR key IN ${keys}
  LET doc = DOCUMENT(${collection}, key)
  FILTER doc
  REMOVE doc IN ${collection}
  RETURN key
`);
const removed = await cursor.all();
const ignored = keys.filter((key) => !removed.includes(key));

Parameters

keys: string[]

An array of document keys to remove.
Optional options: SimpleQueryRemoveByKeysOptions

Options for removing the documents.

Returns Promise<ArangoResponseMetadata & SimpleQueryRemoveByKeysResult<T>>

rename

rename(newName: string): Promise<ArangoResponseMetadata & CollectionMetadata>

Renames the collection and updates the instance's name to newName.

Additionally removes the instance from the Database's internal cache.

Note: Renaming collections may not be supported when ArangoDB is running in a cluster configuration.

example

const db = new Database();
const collection1 = db.collection("some-collection");
await collection1.rename("other-collection");
const collection2 = db.collection("some-collection");
const collection3 = db.collection("other-collection");
// Note all three collection instances are different objects but
// collection1 and collection3 represent the same ArangoDB collection!

Parameters

newName: string

The new name of the collection.

Returns Promise<ArangoResponseMetadata & CollectionMetadata>

replace

replace(selector: DocumentSelector, newData: DocumentData<T>, options?: CollectionReplaceOptions): Promise<DocumentMetadata & { new?: Document<T>; old?: Document<T> }>

Replaces an existing document in the collection.

Throws an exception when passed a document or _id from a different collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.save({ _key: "a", color: "blue", count: 1 });
const result = await collection.replace(
  "a",
  { color: "red" },
  { returnNew: true }
);
console.log(result.new.color, result.new.count); // "red" undefined
```
Parameters
- selector: DocumentSelector
  
  Document _key, _id or object with either of those properties (e.g. a document from this collection).
- newData: DocumentData<T>
  
  The contents of the new document.
- Optional options: CollectionReplaceOptions
  
  Options for replacing the document.
Returns Promise<DocumentMetadata & { new?: Document<T>; old?: Document<T> }>

replaceAll

replaceAll(newData: ((T & Partial<DocumentMetadata> & Partial<EdgeMetadata> & { _key: string }) | (T & Partial<DocumentMetadata> & Partial<EdgeMetadata> & { _id: string }))[], options?: CollectionReplaceOptions): Promise<(DocumentMetadata & { new?: Document<T>; old?: Document<T> })[]>

Replaces existing documents in the collection, identified by the _key or _id of each document.

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.save({ _key: "a", color: "blue", count: 1 });
await collection.save({ _key: "b", color: "green", count: 3 });
const result = await collection.replaceAll(
  [
    { _key: "a", color: "red" },
    { _key: "b", color: "yellow", count: 2 }
  ],
  { returnNew: true }
);
console.log(result[0].new.color, result[0].new.count); // "red" undefined
console.log(result[1].new.color, result[1].new.count); // "yellow" 2

Parameters

newData: ((T & Partial<DocumentMetadata> & Partial<EdgeMetadata> & { _key: string }) | (T & Partial<DocumentMetadata> & Partial<EdgeMetadata> & { _id: string }))[]

The documents to replace.
Optional options: CollectionReplaceOptions

Options for replacing the documents.

Returns Promise<(DocumentMetadata & { new?: Document<T>; old?: Document<T> })[]>

replaceByExample

replaceByExample(example: Partial<DocumentData<T>>, newValue: DocumentData<T>, options?: SimpleQueryRemoveByExampleOptions): Promise<ArangoResponseMetadata & SimpleQueryReplaceByExampleResult>

Replaces all documents in the collection matching the given example.

deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example

const db = new Database();
const collection = db.collection("some-collection");
const newValue = { flavor: "chocolate" };
// const { replaced } = await collection.replaceByExample(
//   { flavor: "strawberry" },
//   newValue
// );
const cursor = await db.query(aql`
  RETURN LENGTH(
    FOR doc IN ${collection}
    FILTER doc.flavor == "strawberry"
    REPLACE doc WITH ${newValue} IN ${collection}
    RETURN 1
  )
`);
const replaced = await cursor.next();

Parameters

example: Partial<DocumentData<T>>

An object representing an example for the documents.
newValue: DocumentData<T>

Document data to replace the matching documents with.
Optional options: SimpleQueryRemoveByExampleOptions

Options for replacing the documents.

Returns Promise<ArangoResponseMetadata & SimpleQueryReplaceByExampleResult>

revision

revision(): Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { revision: string }>

Retrieves the collection revision ID.

example

const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.revision();
// data contains the collection's revision

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { revision: string }>

rotate

rotate(): Promise<boolean>

(MMFiles single-server only.) Rotates the journal of the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const rotated = await collection.rotate();

Returns Promise<boolean>

save

save(data: DocumentData<T>, options?: CollectionInsertOptions): Promise<DocumentMetadata & { new?: Document<T> }>

Inserts a new document with the given data into the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const result = await collection.save(
  { _key: "a", color: "blue", count: 1 },
  { returnNew: true }
);
console.log(result.new.color, result.new.count); // "blue" 1

Parameters

data: DocumentData<T>

The contents of the new document.
Optional options: CollectionInsertOptions

Options for inserting the document.

Returns Promise<DocumentMetadata & { new?: Document<T> }>

saveAll

saveAll(data: DocumentData<T>[], options?: CollectionInsertOptions): Promise<(DocumentMetadata & { new?: Document<T> })[]>

Inserts new documents with the given data into the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
const result = await collection.saveAll(
  [
    { _key: "a", color: "blue", count: 1 },
    { _key: "b", color: "red", count: 2 },
  ],
  { returnNew: true }
);
console.log(result[0].new.color, result[0].new.count); // "blue" 1
console.log(result[1].new.color, result[1].new.count); // "red" 2

Parameters

data: DocumentData<T>[]

The contents of the new documents.
Optional options: CollectionInsertOptions

Options for inserting the documents.

Returns Promise<(DocumentMetadata & { new?: Document<T> })[]>

truncate

truncate(): Promise<ArangoResponseMetadata & CollectionMetadata>

Deletes all documents in the collection.

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.truncate();
// millions of documents cry out in terror and are suddenly silenced,
// the collection "some-collection" is now empty

Returns Promise<ArangoResponseMetadata & CollectionMetadata>

unload

unload(): Promise<ArangoResponseMetadata & CollectionMetadata>

Instructs ArangoDB to remove the collection from memory.

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.unload();
// the collection has now been unloaded from memory

Returns Promise<ArangoResponseMetadata & CollectionMetadata>

update

update(selector: DocumentSelector, newData: Patch<DocumentData<T>>, options?: CollectionUpdateOptions): Promise<DocumentMetadata & { new?: Document<T>; old?: Document<T> }>

Updates an existing document in the collection.

Throws an exception when passed a document or _id from a different collection.
example
```
const db = new Database();
const collection = db.collection("some-collection");
await collection.save({ _key: "a", color: "blue", count: 1 });
const result = await collection.update(
  "a",
  { count: 2 },
  { returnNew: true }
);
console.log(result.new.color, result.new.count); // "blue" 2
```
Parameters
- selector: DocumentSelector
  
  Document _key, _id or object with either of those properties (e.g. a document from this collection).
- newData: Patch<DocumentData<T>>
  
  The data for updating the document.
- Optional options: CollectionUpdateOptions
  
  Options for updating the document.
Returns Promise<DocumentMetadata & { new?: Document<T>; old?: Document<T> }>

updateAll

updateAll(newData: ((Patch<DocumentData<T>> & { _key: string }) | (Patch<DocumentData<T>> & { _id: string }))[], options?: CollectionUpdateOptions): Promise<(DocumentMetadata & { new?: Document<T>; old?: Document<T> })[]>

Updates existing documents in the collection, identified by the _key or _id of each document.

example

const db = new Database();
const collection = db.collection("some-collection");
await collection.save({ _key: "a", color: "blue", count: 1 });
await collection.save({ _key: "b", color: "green", count: 3 });
const result = await collection.updateAll(
  [
    { _key: "a", count: 2 },
    { _key: "b", count: 4 }
  ],
  { returnNew: true }
);
console.log(result[0].new.color, result[0].new.count); // "blue" 2
console.log(result[1].new.color, result[1].new.count); // "green" 4

Parameters

newData: ((Patch<DocumentData<T>> & { _key: string }) | (Patch<DocumentData<T>> & { _id: string }))[]

The data for updating the documents.
Optional options: CollectionUpdateOptions

Options for updating the documents.

Returns Promise<(DocumentMetadata & { new?: Document<T>; old?: Document<T> })[]>

updateByExample

updateByExample(example: Partial<DocumentData<T>>, newValue: Patch<DocumentData<T>>, options?: SimpleQueryUpdateByExampleOptions): Promise<ArangoResponseMetadata & SimpleQueryUpdateByExampleResult>

Updates all documents in the collection matching the given example.
deprecated

Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.

example
```
const db = new Database();
const collection = db.collection("some-collection");
const newData = { color: "red" };
// const { updated } = await collection.updateByExample(
//   { flavor: "strawberry" },
//   newValue
// );
const cursor = await db.query(aql`
  RETURN LENGTH(
    FOR doc IN ${collection}
    FILTER doc.flavor == "strawberry"
    UPDATE doc WITH ${newValue} IN ${collection}
    RETURN 1
  )
`);
const updated = await cursor.next();
```
Parameters
- example: Partial<DocumentData<T>>
  
  An object representing an example for the documents.
- newValue: Patch<DocumentData<T>>
  
  Document data to update the matching documents with.
- Optional options: SimpleQueryUpdateByExampleOptions
  
  Options for updating the documents.
Returns Promise<ArangoResponseMetadata & SimpleQueryUpdateByExampleResult>

Type parameters

T: Record<string, unknown> = any

Hierarchy

Index

Properties

Methods

Properties

Readonly isArangoCollection

Readonly name

Methods

all

Parameters

Optional options: SimpleQueryAllOptions

Returns Promise<ArrayCursor<Document<T>>>

any

Returns Promise<Document<T>>

byExample

Parameters

example: Partial<DocumentData<T>>

Optional options: SimpleQueryByExampleOptions

Returns Promise<ArrayCursor<Document<T>>>

checksum

Parameters

Optional options: CollectionChecksumOptions

Returns Promise<ArangoResponseMetadata & CollectionMetadata & { checksum: string; revision: string }>

count

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties & { count: number }>

create

Parameters

Optional options: CreateCollectionOptions & { type?: DOCUMENT_COLLECTION | EDGE_COLLECTION }

Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

document

Parameters

selector: DocumentSelector

Optional options: CollectionReadOptions

Returns Promise<Document<T>>

Parameters

selector: DocumentSelector

graceful: boolean

Returns Promise<Document<T>>

documentExists

Parameters

selector: DocumentSelector

Returns Promise<boolean>

documentId

Parameters

selector: DocumentSelector

Returns string

documents

Parameters

selectors: (string | ObjectWithKey)[]

Optional options: CollectionBatchReadOptions

Returns Promise<Document<T>[]>

drop

Parameters

Optional options: CollectionDropOptions

Returns Promise<ArangoResponseMetadata>

dropIndex

Parameters

selector: IndexSelector

Returns Promise<ArangoResponseMetadata & { id: string }>

ensureIndex

Parameters

details: EnsurePersistentIndexOptions

Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; type: "persistent" } & { isNewlyCreated: boolean }>

Parameters

details: EnsureHashIndexOptions

Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; selectivityEstimate: number; type: "hash" } & { isNewlyCreated: boolean }>

Parameters

details: EnsureSkiplistIndexOptions

Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: string[]; type: "skiplist" } & { isNewlyCreated: boolean }>

Parameters

details: EnsureTtlIndexOptions

Returns Promise<ArangoResponseMetadata & GenericIndex & { expireAfter: number; fields: [string]; selectivityEstimate: number; type: "ttl" } & { isNewlyCreated: boolean }>

Parameters

details: EnsureFulltextIndexOptions

Returns Promise<ArangoResponseMetadata & GenericIndex & { fields: [string]; minLength: number; type: "fulltext" } & { isNewlyCreated: boolean }>

Parameters

details: EnsureGeoIndexOptions

Returns Promise<ArangoResponseMetadata & GenericIndex & { bestIndexedLevel: number; fields: [string] | [string, string]; geoJson: boolean; maxNumCoverCells: number; type: "geo"; worstIndexedLevel: number } & { isNewlyCreated: boolean }>