Readonly nameName of the collection.
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, or if the document does not exist.
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("Document does not exist");
}
Retrieves the document matching the given key or id.
Throws an exception when passed a document or _id from a different
collection, or if the document does not exist.
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("Document does not exist");
}
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
Retrieves a list of all edges of the document matching the given
selector.
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: CollectionEdgesOptionsOptions for retrieving the edges.
const db = new Database();
const collection = db.collection("edges");
await collection.import([
["_key", "_from", "_to"],
["x", "vertices/a", "vertices/b"],
["y", "vertices/a", "vertices/c"],
["z", "vertices/d", "vertices/a"],
]);
const edges = await collection.edges("vertices/a");
console.log(edges.map((edge) => edge._key)); // ["x", "y", "z"]
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" }]
});
Creates an index on the collection if it does not already exist.
Options for creating the 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
});
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 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
Retrieves the shardId of the shard responsible for the given document.
Document in the collection to look up the shardId of.
const db = new Database();
const collection = db.collection("some-collection");
const responsibleShard = await collection.getResponsibleShard();
Bulk imports the given data into the collection.
The data to import, as an array of edge data.
Optional options: CollectionImportOptionsOptions for importing the data.
const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
[
{ _key: "x", _from: "vertices/a", _to: "vertices/b", weight: 1 },
{ _key: "y", _from: "vertices/a", _to: "vertices/c", weight: 2 }
]
);
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 edge document.
Optional options: CollectionImportOptionsOptions for importing the data.
const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
[
[ "_key", "_from", "_to", "weight" ],
[ "x", "vertices/a", "vertices/b", 1 ],
[ "y", "vertices/a", "vertices/c", 2 ]
]
);
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 edge 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
edge 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":"x","_from":"vertices/a","_to":"vertices/b","weight":1}\r\n' +
'{"_key":"y","_from":"vertices/a","_to":"vertices/c","weight":2}\r\n',
{ type: "documents" } // or "auto"
);
const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
'[{"_key":"x","_from":"vertices/a","_to":"vertices/b","weight":1},' +
'{"_key":"y","_from":"vertices/a","_to":"vertices/c","weight":2}]',
{ type: "list" } // or "auto"
);
const db = new Database();
const collection = db.collection("some-collection");
await collection.import(
'["_key","_from","_to","weight"]\r\n' +
'["x","vertices/a","vertices/b",1]\r\n' +
'["y","vertices/a","vertices/c",2]\r\n'
);
Retrieves a list of all incoming edges of the document matching the given
selector.
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: CollectionEdgesOptionsOptions for retrieving the edges.
const db = new Database();
const collection = db.collection("edges");
await collection.import([
["_key", "_from", "_to"],
["x", "vertices/a", "vertices/b"],
["y", "vertices/a", "vertices/c"],
["z", "vertices/d", "vertices/a"],
]);
const edges = await collection.inEdges("vertices/a");
console.log(edges.map((edge) => edge._key)); // ["z"]
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 options: IndexListOptionsOptions for fetching the index list.
const db = new Database();
const collection = db.collection("some-collection");
const indexes = await collection.indexes();
const db = new Database();
const collection = db.collection("some-collection");
const allIndexes = await collection.indexes<HiddenIndex>({
withHidden: true
});
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 a list of all outgoing edges of the document matching the given
selector.
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: CollectionEdgesOptionsOptions for retrieving the edges.
const db = new Database();
const collection = db.collection("edges");
await collection.import([
["_key", "_from", "_to"],
["x", "vertices/a", "vertices/b"],
["y", "vertices/a", "vertices/c"],
["z", "vertices/d", "vertices/a"],
]);
const edges = await collection.outEdges("vertices/a");
console.log(edges.map((edge) => edge._key)); // ["x", "y"]
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
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("friends");
const doc = await collection.document("musadir");
await collection.remove(doc);
// document with key "musadir" 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: CollectionRemoveOptionsOptions for removing the documents.
const db = new Database();
const collection = db.collection("friends");
await collection.removeAll(["musadir", "salman"]);
// document with keys "musadir" and "salman" deleted
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("friends");
await collection.save(
{
_key: "musadir",
_from: "users/rana",
_to: "users/mudasir",
active: true,
best: true
}
);
const result = await collection.replace(
"musadir",
{ active: false },
{ returnNew: true }
);
console.log(result.new.active, result.new.best); // false undefined
Replaces existing documents in the collection, identified by the _key or
_id of each document.
The documents to replace.
Optional options: CollectionReplaceOptionsOptions for replacing the documents.
const db = new Database();
const collection = db.collection("friends");
await collection.save(
{
_key: "musadir",
_from: "users/rana",
_to: "users/mudasir",
active: true,
best: true
}
);
await collection.save(
{
_key: "salman",
_from: "users/rana",
_to: "users/salman",
active: false,
best: false
}
);
const result = await collection.replaceAll(
[
{ _key: "musadir", active: false },
{ _key: "salman", active: true, best: true }
],
{ returnNew: true }
);
console.log(result[0].new.active, result[0].new.best); // false undefined
console.log(result[1].new.active, result[1].new.best); // true true
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("friends");
const result = await collection.save(
{ _from: "users/rana", _to: "users/mudasir", active: false },
{ returnNew: true }
);
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("friends");
const result = await collection.saveAll(
[
{ _from: "users/rana", _to: "users/mudasir", active: false },
{ _from: "users/rana", _to: "users/salman", active: true }
],
{ returnNew: true }
);
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("friends");
await collection.save(
{
_key: "musadir",
_from: "users/rana",
_to: "users/mudasir",
active: true,
best: true
}
);
const result = await collection.update(
"musadir",
{ active: false },
{ returnNew: true }
);
console.log(result.new.active, result.new.best); // false true
Updates existing documents in the collection, identified by the _key or
_id of each document.
The data for updating the documents.
Optional options: CollectionUpdateOptionsOptions for updating the documents.
const db = new Database();
const collection = db.collection("friends");
await collection.save(
{
_key: "musadir",
_from: "users/rana",
_to: "users/mudasir",
active: true,
best: true
}
);
await collection.save(
{
_key: "salman",
_from: "users/rana",
_to: "users/salman",
active: false,
best: false
}
);
const result = await collection.updateAll(
[
{ _key: "musadir", active: false },
{ _key: "salman", active: true, best: true }
],
{ returnNew: true }
);
console.log(result[0].new.active, result[0].new.best); // false true
console.log(result[1].new.active, result[1].new.best); // true true
Represents an edge collection in a database.Database.
See DocumentCollection for a more generic variant of this interface more suited for regular document collections.
See also graph.GraphEdgeCollection for the type representing an edge collection in a graph.Graph.
When using TypeScript, collections can be cast to a specific edge document data type to increase type safety.
Param: T
Type to use for edge document data. Defaults to
any.Example