Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface DocumentCollection<T>

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, any> = any

    Type to use for document data. Defaults to any.

Hierarchy

Index

Properties

Readonly isArangoCollection

isArangoCollection: true
internal

Indicates that this object represents an ArangoDB collection.

Readonly name

name: string

Name of the collection.

Methods

all

  • 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

    Returns Promise<ArrayCursor<Document<T>>>

any

  • 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

  • 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

    Returns Promise<ArrayCursor<Document<T>>>

checksum

  • 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

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

compact

  • 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
    

    Returns Promise<ArangoResponseMetadata>

count

  • 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

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

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

    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

    Returns Promise<ArangoResponseMetadata & CollectionMetadata & CollectionProperties>

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

  • 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

  • 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

  • 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

  • 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

    Returns Promise<ArangoResponseMetadata>

dropIndex

  • 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

  • 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

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

    Hash indexes have been deprecated in ArangoDB 3.9 and should be replaced with persistent indexes.

    Parameters

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

    Skiplist indexes have been deprecated in ArangoDB 3.9 and should be replaced with persistent indexes.

    Parameters

    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

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

  • 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: "zkd",
      fields: ["x", "y", "z"],
      fieldValueTypes: "double"
    });
    
    
    

    Parameters

    Returns Promise<ArangoResponseMetadata & GenericIndex & { fieldValueTypes: "double"; fields: string[]; type: "zkd" } & { 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

    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

    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

  • 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

  • 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

  • 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

  • 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

  • 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

    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

  • 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

  • (MMFiles only.) 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
    
    deprecated

    This method was deprecated in ArangoDB 3.8 as it no longer has any effect since the MMFiles storage engine was removed in ArangoDB 3.7.

    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

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

  • 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

  • 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

  • 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

    Returns Promise<ArangoResponseMetadata & SimpleQueryRemoveByExampleResult>

removeByKeys

  • 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

    Returns Promise<ArangoResponseMetadata & SimpleQueryRemoveByKeysResult<T>>

rename

  • 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

  • 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

  • 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

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

replaceByExample

  • 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

    Returns Promise<ArangoResponseMetadata & SimpleQueryReplaceByExampleResult>

revision

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

    The MMFiles storage engine was removed in ArangoDB 3.7.

    Returns Promise<boolean>

save

  • 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

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

saveAll

  • 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

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

truncate

  • 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

  • (MMFiles only.) 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
    
    deprecated

    This method was deprecated in ArangoDB 3.8 as it no longer has any effect since the MMFiles storage engine was removed in ArangoDB 3.7.

    Returns Promise<ArangoResponseMetadata & CollectionMetadata>

update

  • 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

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

updateAll

  • 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

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

updateByExample

  • 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

    Returns Promise<ArangoResponseMetadata & SimpleQueryUpdateByExampleResult>

Generated using TypeDoc