Readonly nameName of the collection.
Retrieves all documents in the collection.
Optional options: SimpleQueryAllOptionsOptions for retrieving the documents.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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
`);
Retrieves a random document from the collection.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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();
Retrieves all documents in the collection matching the given example.
An object representing an example for documents.
Optional options: SimpleQueryByExampleOptionsOptions for retrieving the documents.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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
`);
Retrieves the collection checksum.
Optional options: CollectionChecksumOptionsOptions for retrieving the checksum.
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.checksum();
// data contains the collection's checksum
Triggers compaction for a collection.
const db = new Database();
const collection = db.collection("some-collection");
await collection.compact();
// Background compaction is triggered on the collection
Retrieves information about the number of documents in a collection.
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.count();
// data contains the collection's count
Creates a collection with the given options and the instance's name.
See also database.Database#createCollection and database.Database#createEdgeCollection.
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).
Optional options: CreateCollectionOptions & { Options for creating the collection.
const db = new Database();
const collection = db.collection("potatoes");
await collection.create();
// the document collection "potatoes" now exists
const db = new Database();
const collection = db.collection("friends");
await collection.create({ type: CollectionType.EDGE_COLLECTION });
// the edge collection "friends" now exists
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
Retrieves the document matching the given key or id.
Throws an exception when passed a document or _id from a different
collection.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
Optional options: CollectionReadOptionsOptions for retrieving the document.
const db = new Database();
const collection = db.collection("some-collection");
try {
const document = await collection.document("abc123");
console.log(document);
} catch (e: any) {
console.error("Could not find document");
}
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");
}
Retrieves the document matching the given key or id.
Throws an exception when passed a document or _id from a different
collection.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
If set to true, null is returned instead of an
exception being thrown if the document does not exist.
const db = new Database();
const collection = db.collection("some-collection");
try {
const document = await collection.document("abc123", false);
console.log(document);
} catch (e: any) {
console.error("Could not find document");
}
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");
}
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.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
Optional options: DocumentExistsOptionsconst db = new Database();
const collection = db.collection("some-collection");
const exists = await collection.documentExists("abc123");
if (!exists) {
console.log("Document does not exist");
}
Derives a document _id from the given selector for this collection.
Throws an exception when passed a document or _id from a different
collection.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
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
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
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.
Array of document _key, _id or objects with either
of those properties (e.g. a document from this collection).
Optional options: CollectionBatchReadOptionsOptions for retrieving the documents.
const db = new Database();
const collection = db.collection("some-collection");
try {
const documents = await collection.documents(["abc123", "xyz456"]);
console.log(documents);
} catch (e: any) {
console.error("Could not find document");
}
Deletes the collection from the database.
Optional options: CollectionDropOptionsOptions for dropping the collection.
const db = new Database();
const collection = db.collection("some-collection");
await collection.drop();
// The collection "some-collection" is now an ex-collection
Deletes the index with the given name or id from the database.
Index name, id or object with either property.
const db = new Database();
const collection = db.collection("some-collection");
await collection.dropIndex("some-index");
// The index "some-index" no longer exists
Creates a persistent index on the collection if it does not already exist.
Options for creating the persistent index.
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
});
Creates a TTL index on the collection if it does not already exist.
Options for creating the TTL index.
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
});
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
});
Creates a multi-dimensional index on the collection if it does not already exist.
Options for creating the multi-dimensional index.
const db = new Database();
const collection = db.collection("some-points");
// Create a multi-dimensional index for the attributes x, y and z
await collection.ensureIndex({
type: "mdi",
fields: ["x", "y", "z"],
fieldValueTypes: "double"
});
Creates a geo index on the collection if it does not already exist.
Options for creating the geo index.
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
});
Creates a inverted index on the collection if it does not already exist.
Options for creating the inverted index.
const db = new Database();
const collection = db.collection("some-collection");
// Create an inverted index
await collection.ensureIndex({
type: "inverted",
fields: ["a", { name: "b", analyzer: "text_en" }]
});
Retrieves statistics for a collection.
Optional details: booleanwhether to return extended storage engine-specific details to the figures, which may cause additional load and impact performance
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.figures();
// data contains the collection's figures
Retrieves a single document in the collection matching the given example.
An object representing an example for the document.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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();
Performs a fulltext query in the given attribute on the collection.
Name of the field to search.
Fulltext query string to search for.
Optional options: SimpleQueryFulltextOptionsOptions for performing the fulltext query.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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
`);
Retrieves general information about the collection.
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.get();
// data contains general information about the collection
Bulk imports the given data into the collection.
The data to import, as an array of document data.
Optional options: CollectionImportOptionsOptions for importing the data.
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" }
]
);
Bulk imports the given data into the collection.
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: CollectionImportOptionsOptions for importing the data.
const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
[
[ "_key", "password" ],
[ "jcd", "bionicman" ],
[ "jreyes", "amigo" ],
[ "ghermann", "zeitgeist" ]
]
);
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".
The data to import as a Buffer (Node), Blob (browser) or string.
Optional options: CollectionImportOptions & { Options for importing the data.
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"
);
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"
);
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'
);
Returns an index description by name or id if it exists.
Index name, id or object with either property.
const db = new Database();
const collection = db.collection("some-collection");
const index = await collection.index("some-index");
Returns a list of all index descriptions for the collection.
Optional withHidden: booleanIf set to true, includes indexes that are not yet
fully built but are in the building phase. Default: false.
const db = new Database();
const collection = db.collection("some-collection");
const indexes = await collection.indexes();
Returns a list of all index descriptions for the collection.
Optional withHidden: booleanIf set to true, includes indexes that are not yet
fully built but are in the building phase. Default: false.
const db = new Database();
const collection = db.collection("some-collection");
const indexes = await collection.indexes(true);
Retrieves a list of references for all documents in the collection.
Optional type: SimpleQueryListTypeThe type of document reference to retrieve.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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
`);
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
`);
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)
`);
(RocksDB only.) Instructs ArangoDB to load as many indexes of the collection into memory as permitted by the memory limit.
const db = new Database();
const collection = db.collection("indexed-collection");
await collection.loadIndexes();
// the indexes are now loaded into memory
Retrieves all documents matching the given document keys.
An array of document keys to look up.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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();
Retrieves the collection's properties.
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.properties();
// data contains the collection's properties
Replaces the properties of the collection.
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
(RocksDB only.) Instructs ArangoDB to recalculate the collection's document count to fix any inconsistencies.
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
Removes an existing document from the collection.
Throws an exception when passed a document or _id from a different
collection.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
Optional options: CollectionRemoveOptionsOptions for removing the document.
const db = new Database();
const collection = db.collection("some-collection");
await collection.remove("abc123");
// document with key "abc123" deleted
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
Removes existing documents from the collection.
Throws an exception when passed any document or _id from a different
collection.
Documents _key, _id or objects with either of those
properties (e.g. documents from this collection).
Optional options: Omit<CollectionRemoveOptions, "ifMatch">Options for removing the documents.
const db = new Database();
const collection = db.collection("some-collection");
await collection.removeAll(["abc123", "def456"]);
// document with keys "abc123" and "def456" deleted
Removes all documents in the collection matching the given example.
An object representing an example for the document.
Optional options: SimpleQueryRemoveByExampleOptionsOptions for removing the documents.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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();
Removes all documents matching the given document keys.
An array of document keys to remove.
Optional options: SimpleQueryRemoveByKeysOptionsOptions for removing the documents.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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));
Renames the collection and updates the instance's name to newName.
Additionally removes the instance from the database.Database's internal cache.
Note: Renaming collections may not be supported when ArangoDB is running in a cluster configuration.
The new name of the collection.
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!
Replaces an existing document in the collection.
Throws an exception when passed a document or _id from a different
collection.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
The contents of the new document.
Optional options: CollectionReplaceOptionsOptions for replacing the document.
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
Replaces existing documents in the collection, identified by the _key or
_id of each document.
The documents to replace.
Optional options: Omit<CollectionReplaceOptions, "ifMatch">Options for replacing the documents.
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
Replaces all documents in the collection matching the given example.
An object representing an example for the documents.
Document data to replace the matching documents with.
Optional options: SimpleQueryRemoveByExampleOptionsOptions for replacing the documents.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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();
Retrieves the collection revision ID.
const db = new Database();
const collection = db.collection("some-collection");
const data = await collection.revision();
// data contains the collection's revision
Inserts a new document with the given data into the collection.
The contents of the new document.
Optional options: CollectionInsertOptionsOptions for inserting the document.
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
Inserts new documents with the given data into the collection.
The contents of the new documents.
Optional options: CollectionInsertOptionsOptions for inserting the documents.
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
Deletes all documents in the collection.
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
Updates an existing document in the collection.
Throws an exception when passed a document or _id from a different
collection.
Document _key, _id or object with either of those
properties (e.g. a document from this collection).
The data for updating the document.
Optional options: CollectionUpdateOptionsOptions for updating the document.
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
Updates existing documents in the collection, identified by the _key or
_id of each document.
The data for updating the documents.
Optional options: Omit<CollectionUpdateOptions, "ifMatch">Options for updating the documents.
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
Updates all documents in the collection matching the given example.
An object representing an example for the documents.
Document data to update the matching documents with.
Optional options: SimpleQueryUpdateByExampleOptionsOptions for updating the documents.
Simple Queries have been deprecated in ArangoDB 3.4 and can be replaced with AQL queries.
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();
Represents an document collection in a database.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