Interface DocumentCollection<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
`);

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();

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
`);

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

Triggers compaction for a collection.

Example

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.

Example

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 createCollection and 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).

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

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: any) {
  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");
}

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: any) {
  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");
}

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");
}

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

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: any) {
  console.error("Could not find document");
}

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

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

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
});

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
});

Creates a multi-dimensional index on the collection if it does not already exist.

Example

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 fulltext index on the collection if it does not already exist.

Deprecated

Fulltext indexes have been deprecated in ArangoDB 3.10 and should be replaced with ArangoSearch.

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
});

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
});

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

Example

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" }]
});

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

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

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();

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
`);

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

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();

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" }
  ]
);

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" ]
  ]
);

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'
);

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");

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();

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)
`);

(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

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();

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

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

(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

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

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

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();

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));

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!

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

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

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();

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

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

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

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

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

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