From cb351dd63d5141fb096f333a376e898f9c2c256a Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Wed, 4 Dec 2024 16:07:03 +0100 Subject: [PATCH 1/9] Add interface examples for databases, collection, Views --- .../concepts/data-structure/collections.md | 584 +++++++++++++++++- .../3.12/concepts/data-structure/databases.md | 476 +++++++++++++- .../3.12/concepts/data-structure/views.md | 520 ++++++++++++++-- site/content/3.12/develop/drivers/go.md | 4 +- .../3.12/develop/http-api/views/_index.md | 8 + 5 files changed, 1494 insertions(+), 98 deletions(-) diff --git a/site/content/3.12/concepts/data-structure/collections.md b/site/content/3.12/concepts/data-structure/collections.md index 738593018..936d09482 100644 --- a/site/content/3.12/concepts/data-structure/collections.md +++ b/site/content/3.12/concepts/data-structure/collections.md @@ -143,47 +143,593 @@ attempt. Even if an insert fails, the auto-increment value is never rolled back. That means there may exist gaps in the sequence of assigned auto-increment values if inserts fails. -## Collections API +## Collection interfaces -The following descriptions cover the JavaScript interface for collections that -you can use to handle collections from the _arangosh_ command-line tool, as -well as in server-side JavaScript code like Foxx microservices. -For other languages see the corresponding language API. +The following sections show examples of how you can use the APIs of ArangoDB and +the official drivers, as well as the built-in web interface, to perform common +operations related to collections. For less common operations and other drivers, +see the corresponding reference documentation. ### Create a collection -`db._create(collection-name)` +{{< tabs "interfaces" >}} -This call creates a new collection called `collection-name`. -See the [`db` object](../../develop/javascript-api/@arangodb/db-object.md#db_createcollection-name--properties--type--options) +{{< tab "Web interface" >}} +1. Click **Collections** in the main navigation. +2. Click **Add collection**. +3. Set a **Name** and optionally configuration options. +4. Click **Create**. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_create_collection +description: '' +--- +coll = db._create("coll"); +~db._drop("coll"); +``` +See `db._create()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_createcollection-name--properties--type--options) for details. +{{< /tab >}} -### Get a collection +{{< tab "cURL" >}} +```sh +curl -d '{"name":"coll"}' http://localhost:8529/_db/mydb/_api/collection +``` -`db._collection(collection-name)` +See `POST /_db/{database-name}/_api/collection` in the +[HTTP API](../../develop/http-api/databases.md#create-a-database) for details. +{{< /tab >}} -Returns the specified collection. +{{< tab "JavaScript" >}} +```js +const info = await db.createCollection("coll"); +// -- or -- +let coll = db.collection("coll"); +const info = await coll.create(); +``` -For example, assume that the collection identifier is `7254820` and the name is -`demo`, then the collection can be accessed as follows: +See [`Database.createCollection()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createCollection) +and [`DocumentCollection.create()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#create) +in the arangojs documentation for details. +{{< /tab >}} -```js -db._collection("demo") +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.CreateCollection(ctx, "coll") +``` + +See `DatabaseCollection.CreateCollection()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +CollectionEntity coll = db.createCollection("coll"); +// -- or -- +CollectionEntity coll = db.collection("coll").create(); +``` + +See [`ArangoDB.createCollection()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) +and [`ArangoCollection.create()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#create%28%29) +in the arangodb-java-driver documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.create_collection("coll") ``` -If no collection with such a name exists, then `null` is returned. +See `StandardDatabase.create_collection()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_collection) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Get a collection + +{{< tabs "interfaces" >}} +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired collection. +2. Click **Collections** in the main navigation. +3. Click the name or row of the desired collection. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_get_collection +description: '' --- +~db._create("coll"); +coll = db._collection("coll"); +~db._drop("coll"); +``` There is a short-cut that you can use: ```js -db.collection-name +let coll = db.coll // or -db["collection-name"] +let coll = db["coll"] +``` + +See `db._collection()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_collectioncollection) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/collection/coll +``` + +See `GET /_db/{database-name}/_api/collection/{collection-name}` in the +[HTTP API](../../develop/http-api/collections.md#get-the-collection-information) +for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); +const info = await coll.get(); +``` + +See `Database.collection()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#collection) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) +``` + +See `DatabaseCollection.Collection()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); +``` + +See `ArangoDB.collection()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") +``` + +See `StandardDatabase.collection()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.collection) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### List all collections + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that you want to list the collection of. +2. Click **Collections** in the main navigation. +3. All collections are listed, given that no **Filters** are applied and you + have at least read access for all collections. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_list_collections +description: '' +--- +~db._createDatabase("mydb"); +~db._useDatabase("mydb"); +~db._create("products"); +~db._create("users"); +db._collections(); +~db._dropDatabase("mydb"); +``` + +See `db._collections()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#collections) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/collection +``` + +See `GET /_db/{database-name}/_api/collection` in the +[HTTP API](../../develop/http-api/collections.md#get-the-collection-information) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +const colls = await db.collections(); +``` + +See `Database.collections()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#collections) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +colls, err := db.Collections(ctx) +``` + +See `DatabaseCollection.Collections()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +Collection colls = db.getCollections(); +``` + +See `ArangoDatabase.getCollections()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#getCollections%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +colls = db.collections() +``` + +See `StandardDatabase.collections()` in the [python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.collections) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Remove a collection + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired collection. +2. Click **Collections** in the main navigation. +3. Click the name or row of the desired collection. +4. Go to the **Settings** tab. +5. Click the **Delete** button and confirm. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_delete_collection +render: input +description: '' +--- +~db._create("coll"); +db._drop("coll"); +``` + +See `db._drop()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_dropcollection--options) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -XDELETE http://localhost:8529/_db/mydb/_api/collection/coll +``` + +See `DELETE /_db/{database-name}/_api/collection/{collection-name}` in the +[HTTP API](../../develop/http-api/collections.md#drop-a-collection) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); +const status = await coll.drop(); +``` + +See `DocumentCollection.drop()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#drop) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) +err = coll.Remove(ctx) +``` + +See `Collection.Remove()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); +coll.drop(); +``` + +See `ArangoCollection.drop()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#drop%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +ok = db.delete_collection("coll") +``` + +See `StandardDatabase.delete_collection()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_collection) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Get collection properties + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired collection. +2. Click **Collections** in the main navigation. +3. Click the name or row of the desired collection. +4. The properties are listed in the **Info**, **Computed Values**, and + **Schema** tabs. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_get_collection_properties +description: '' +--- +~db._create("coll"); +coll = db._collection("coll"); +coll.properties(); +~db._drop("coll"); +``` + +See `collection.properties()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/collection/coll/properties +``` + +See `GET /_db/{database-name}/_api/collection/{collection-name}/properties` in the +[HTTP API](../../develop/http-api/collections.md#get-the-properties-of-a-collection) +for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); +const props = await coll.properties(); ``` -This property access returns the collection named `collection-name`. +See `DocumentCollection.properties()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) +props, err := coll.Properties() +``` + +See `Collection.Properties()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); +CollectionPropertiesEntity = coll.getProperties(); +``` + +See `ArangoCollection.getProperties()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#getProperties%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") +props = coll.properties() +``` + +See `Collection.properties()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.properties) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Set collection properties + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired collection. +2. Click **Collections** in the main navigation. +3. Click the name or row of the desired collection. +4. The properties you can change are listed in the **Settings**, + **Computed Values**, and **Schema** tabs. +5. Make the desired changes and click the **Save** button. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_set_collection_properties +description: '' +--- +~db._create("coll"); +coll = db._collection("coll"); +coll.properties({ + waitForSync: true, + schema: { + rule: { + type: "object", + properties: { + attr: { + type: "number", + minimum: 10 + } + } + } + } +}); +~db._drop("coll"); +``` + +See `collection.properties()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/collection/coll/properties +``` + +See `GET /_db/{database-name}/_api/collection/{collection-name}/properties` in the +[HTTP API](../../develop/http-api/collections.md#get-the-properties-of-a-collection) +for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); +const props = await coll.properties({ + waitForSync: true, + schema: { + rule: { + type: "object", + properties: { + attr: { + type: "number", + minimum: 10 + } + } + } + } +}); +``` + +See `DocumentCollection.properties()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties.properties-2) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) +err = coll.SetProperties(ctx, arangodb.SetCollectionPropertiesOptions{ + WaitForSync: utils.NewType(true), + Schema: &arangodb.CollectionSchemaOptions{ + Rule: map[string]interface{} { + "type": "object", + "properties": map[string]interface{} { + "attr": map[string]interface{} { + "type": "number", + "minimum": 10, + } + } + } + } +}) +``` + +See `Collection.SetProperties()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +String schemaRule = ( + "{" + + " \"type\": \"object\"," + + " \"properties\": {" + + " \"attr\": {" + + " \"type\": \"number\"," + + " \"minimum\": 10" + + " }" + + " }" + + "}"); + +CollectionPropertiesOptions props = new CollectionPropertiesOptions() + .waitForSync(true) + .schema(new CollectionSchema() + .setRule(schemaRule) + ); + +ArangoCollection coll = db.collection("coll"); +CollectionPropertiesEntity = coll.changeProperties(props); +``` + +See `ArangoCollection.changeProperties()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#changeProperties%28com.arangodb.model.CollectionPropertiesOptions%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") +props = coll.configure( + sync=True, + schema={ + "rule": { + "type": "object", + "properties": { + "attr": { + "type": "number", + "minimum": 10 + } + } + } + } +) +``` + +See `Collection.configure()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.configure) +for details. +{{< /tab >}} + +{{< /tabs >}} ### Synchronous replication of collections diff --git a/site/content/3.12/concepts/data-structure/databases.md b/site/content/3.12/concepts/data-structure/databases.md index 716b4b890..5d4abb3b8 100644 --- a/site/content/3.12/concepts/data-structure/databases.md +++ b/site/content/3.12/concepts/data-structure/databases.md @@ -125,50 +125,466 @@ apps/ # the instance's application directory The name of `` will be the database's original name or the database's ID if its name contains special characters. -## Databases API +## Database interfaces -The following descriptions cover the JavaScript interface for databases that -you can use to handle databases from the _arangosh_ command-line tool, as -well as in server-side JavaScript code like Foxx microservices. -For other languages see the corresponding language API. +The following sections show examples of how you can use the APIs of ArangoDB and +the official drivers, as well as the built-in web interface, to perform common +operations related to databases. For less common operations and other drivers, +see the corresponding reference documentation. ### Set the database context +Connections in ArangoDB do not contain any state information. All state +information is contained in the request/response data of the HTTP API that all +clients use under the hood. If the database is changed, client drivers need to +store the current database name on their side to later make requests with the +selected database as the context. + +Note that commands, actions, scripts, or AQL queries should never +access multiple databases, even if they exist. The only intended and +supported way in ArangoDB is to use one database at a time for a command, +an action, a script, or a query. Operations started in one database must +not switch the database later and continue operating in another. + +Foxx applications are only available in the context of the database they have +been installed in. A new database only provides access to the system +applications shipped with ArangoDB (the web interface) and no other Foxx +applications until they are explicitly installed for a particular database. + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If you are logged in, click the name of the current database or the swap icon + in the top-right corner. +2. Select a database from the dropdown list. It only lists databases you have at + least read access to. +3. Click **Select DB**. +{{< /tab >}} + +{{< tab "arangosh" >}} When you have an established connection to ArangoDB, the current database can be changed explicitly using the `db._useDatabase()` method. This switches to the specified database (provided it exists and the user can connect to it). From this point on, any following action in the same shell or connection uses the -specified database, unless otherwise specified. +specified database, unless specified otherwise. -{{< info >}} -If the database is changed, client drivers need to store the -current database name on their side, too. This is because connections -in ArangoDB do not contain any state information. All state information -is contained in the HTTP request/response data. -{{< /info >}} +```js +--- +name: arangosh_use_database +# _useDatabase() returns true but does this get rendered? +#render: input +description: '' +--- +~db._createDatabase("mydb"); +db._useDatabase("mydb"); +~db._useDatabase("_system"); +~db._dropDatabase("mydb"); +``` -To connect to a specific database after arangosh has started use the command -described above. It is also possible to specify a database name when invoking -arangosh. For this purpose, use the command-line parameter `--server.database`, -e.g. +See [`db._useDatabase()`](../../develop/javascript-api/@arangodb/db-object.md#db_usedatabasename) +in the JavaScript API for details. + +It is also possible to specify a database name when invoking arangosh. For this +purpose, use the `--server.database` startup option: ```sh -arangosh --server.database test +arangosh --server.database mydb ``` +{{< /tab >}} -Note that commands, actions, scripts or AQL queries should never -access multiple databases, even if they exist. The only intended and -supported way in ArangoDB is to use one database at a time for a command, -an action, a script or a query. Operations started in one database must -not switch the database later and continue operating in another. +{{< tab "cURL" >}} +Setting the database context is not an operation, you rather specify the database in +the URL like a prefix for the path of an endpoint. Omitting `/_db/{database-name}` +is the same as specifying `/_db/_system`. + +```sh +curl http://localhost:8529/_db/mydb/... +``` + +See [Addresses of databases](../../develop/http-api/databases.md#addresses-of-databases) +in the HTTP API for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +// New connection pool +const myDb = new Database("http://localhost:8529", "mydb"); + +// Same connection pool +const otherDb = myDb.database("other"); +``` + +See [`new Database()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#constructor) +and [`Database.database()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#database) +in the arangojs documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +db, err := client.GetDatabase(ctx, "mydb") +``` + +See `ClientDatabase.GetDatabase()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoDatabase db = arangoDB.db("mydb"); +``` + +See `ArangoDB.db()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +db = client.db('mydb') +``` + +See `ArangoClient.db()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.client.ArangoClient.db) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Create a database + +Each database contains its own system collections, which need to be set up when +a database is created. The creation of a database can therefore take a moment. + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Switch to the `_system` database. +2. Click **Databases** in the main navigation. +3. Click **Add database**. +4. Set a **Name** and optionally configuration options. +5. Click **Create**. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_create_database +render: input +description: '' +--- +var ok = db._useDatabase("_system"); // _system database context required +db._createDatabase("mydb"); +~db._dropDatabase("mydb"); +``` + +See `db._createDatabase()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_createdatabasename--options--users) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -d '{"name":"mydb"}' http://localhost:8529/_api/database +``` + +See `POST /_db/_system/_api/database` in the +[HTTP API](../../develop/http-api/databases.md#create-a-database) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +const info = await db.createDatabase("mydb"); +``` + +See `Database.createDatabase()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createDatabase) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +db, err := client.CreateDatabase(ctx, "mydb") +``` + +See `ClientDatabase.CreateDatabase()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +Boolean ok = arangoDB.createDatabase("mydb"); +// -- or -- +ArangoDatabase db = arangoDB.db("mydb"); +Boolean ok = db.create(); +``` + +See [`ArangoDB.createDatabase()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#createDatabase%28java.lang.String%29) +and [`ArangoDatabase.create()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#create%28%29) +in the arangodb-java-driver documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +sys_db = client.db("_system") # _system database context required +ok = sys_db.create_database("mydb") +db = client.db("mydb") +``` + +See `StandardDatabase.create_database()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_database) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Get a database + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Switch to the `_system` database. +2. Click **Databases** in the main navigation. +3. Click the name or the row of the database. + +To switch to the desired database, see [Set the database context](#set-the-database-context). +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_get_database +description: '' +--- +~db._createDatabase("mydb"); +var ok = db._useDatabase("mydb"); +db._properties(); +~db._dropDatabase("mydb"); +``` + +See `db._properties()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_properties) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/database/current +``` + +See `GET /_db/{database-name}/_api/database/current` in the +[HTTP API](../../develop/http-api/databases.md#get-information-about-the-current-database) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +const myDb = db.database("mydb"); +const info = await myDb.get(); +``` + +See `Database.get()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#get) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +db, err := client.GetDatabase(ctx, "mydb", nil) +info, err := db.Info(ctx) +``` + +See `Database.GetDatabase()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Database) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoDatabase db = arangoDB.db("mydb"); +DatabaseEntity info = db.getInfo(); +``` + +See `ArangoDatabase.getInfo()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#getInfo%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +db = client.db("mydb") +info = db.properties() +``` + +See `StandardDatabase.properties()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.properties) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### List all databases + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Switch to the `_system` database. +2. Click **Databases** in the main navigation. +3. All databases are listed, given that no **Filters** are applied. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_list_databases +description: '' +--- +~db._createDatabase("mydb"); +var ok = db._useDatabase("_system"); // _system database context required +db._databases(); +~db._dropDatabase("mydb"); +``` + +See `db._databases()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_databases) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_api/database +``` + +See `GET /_db/_system/_api/database` in the +[HTTP API](../../develop/http-api/databases.md#list-all-databases) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +const dbNames = await db.databases(); +``` + +See `Database.databases()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#databases) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +dbs, err := client.Databases(ctx) +``` + +See `ClientDatabase.Databases()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +Collection dbNames = arangoDB.getDatabases(); +``` + +See `ArangoDB.getDatabases()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#getDatabases%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +sys_db = client.db("_system") # _system database context required +db_names = sys_db.databases() +``` + +See `StandardDatabase.databases()` the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.databases) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Remove a database + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Switch to the `_system` database. +2. Click **Databases** in the main navigation. +3. Click the name or the row of the database you want to delete. +4. Click the **Delete** button and confirm. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_delete_database +description: '' +--- +~db._createDatabase("mydb"); +var ok = db._useDatabase("_system"); // _system database context required +db._dropDatabase("mydb"); +``` + +See `db._dropDatabase()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_dropdatabasename) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -XDELETE http://localhost:8529/_api/database/mydb +``` + +See `DELETE /_db/{database-name}/_api/database` in the +[HTTP API](../../develop/http-api/databases.md#drop-a-database) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +const ok = await db.dropDatabase("mydb"); +``` + +See `Database.dropDatabase()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#dropDatabase) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +db, err := client.GetDatabase(ctx, "mydb", nil) +err = db.Remove(ctx) +``` + +See `Database.Remove()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Database) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoDatabase db = arangoDB.db("mydb"); +Boolean ok = db.drop(); +``` + +See `ArangoDatabase.drop()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#drop%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +sys_db = client.db("_system") # _system database context required +ok = sys_db.delete_database("mydb") +``` -Please keep in mind that each database contains its own system collections, -which need to be set up when a database is created. This makes the creation -of a database take a while. +See `StandardDatabase.delete_database()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_database) +for details. +{{< /tab >}} -Foxx applications -are also available only in the context of the database they have been installed -in. A new database only provides access to the system applications shipped -with ArangoDB (that is the web interface at the moment) and no other Foxx -applications until they are explicitly installed for the particular database. +{{< /tabs >}} \ No newline at end of file diff --git a/site/content/3.12/concepts/data-structure/views.md b/site/content/3.12/concepts/data-structure/views.md index f3019af48..b22a27ad8 100644 --- a/site/content/3.12/concepts/data-structure/views.md +++ b/site/content/3.12/concepts/data-structure/views.md @@ -115,113 +115,539 @@ strings to ensure the identifiers are not clipped or rounded by clients that do not support big integers. Clients should treat the View IDs returned by ArangoDB as opaque strings when they store or use them locally. -## Views API +## View interfaces -The following descriptions cover the JavaScript interface for Views that -you can use to handle Views from the _arangosh_ command-line tool, as -well as in server-side JavaScript code like Foxx microservices. -For other languages see the corresponding language API. +The following sections show examples of how you can use the APIs of ArangoDB and +the official drivers, as well as the built-in web interface, to perform common +operations related to Views. For less common operations and other drivers, +see the corresponding reference documentation. -The following examples show the basic usage of the View API. -For more details, see: +The examples are limited to the basic usage of the View interfaces. +See the following for more details about the different View types and their +configuration: - [`arangosearch` Views](../../index-and-search/arangosearch/arangosearch-views-reference.md) - [`search-alias` Views](../../index-and-search/arangosearch/search-alias-views-reference.md) -- [JavaScript API for Views](../../develop/javascript-api/@arangodb/db-object.md#views) -- [The _view_ object](../../develop/javascript-api/@arangodb/view-object.md) ### Create a View -Create a View with default properties: - +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Click **Views** in the main navigation. +2. Click the **Add view** button. +3. Enter a **Name** for the View that isn't already used by a collection or View. +4. Select the **Type** for the View. +5. You can optionally specify additional settings: + - For a `search-alias` View, you can add inverted indexes to the View now, + but you can also do so later. + - For an `arangosearch` View, you can configure the immutable settings that + you can only set on View creation and not modify later. +{{< /tab >}} + +{{< tab "arangosh" >}} ```js --- name: viewUsage_01 -description: '' +render: input +description: | + Create a View with default properties: --- -~db._create("colA"); -~db._create("colB"); -view = db._createView("myView", "arangosearch", {}); -~addIgnoreCollection("colA"); -~addIgnoreCollection("colB"); +~db._createView("myView", "search-alias"); +var viewSearch = db._createView("myArangoSearchView", "arangosearch"); +var viewAlias = db._createView("mySearchAliasView", "search-alias"); ~addIgnoreView("myView"); +~addIgnoreView("myArangoSearchView"); +~addIgnoreView("mySearchAliasView"); +``` + +See `db._createView()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_createviewname-type--properties) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -d '{"name":"myView1","type":"arangosearch"}' http://localhost:8529/_db/mydb/_api/view +curl -d '{"name":"myView2","type":"search-alias"}' http://localhost:8529/_db/mydb/_api/view +``` + +See `POST /_db/{database-name}/_api/view` in the HTTP API for details: +- [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#create-an-arangosearch-view) +- [`search-alias` View](../../develop/http-api/views/search-alias-views.md#create-a-search-alias-view) +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let viewSearch = db.createView("myArangoSearchView", { type: "arangosearch" }); +let viewAlias = db.createView("mySearchAliasView", { type: "search-alias" }); +``` + +See `Database.createView()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createView) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +viewSearch, err := db.CreateArangoSearchView(ctx, "myArangoSearchView", nil) +viewAlias, err := db.CreateArangoSearchAliasView(ctx, "myArangoSearchView", nil) +``` + +See `DatabaseView.CreateArangoSearchView()` and `DatabaseView.CreateArangoSearchAliasView()` +in the [go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseView) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ViewEntity view1 = db.createView("myView1", ViewType.ARANGO_SEARCH); +ViewEntity view2 = db.createView("myView2", ViewType.SEARCH_ALIAS); + +ViewEntity viewSearch = db.createArangoSearch("myArangoSearchView", null); +ViewEntity viewAlias = db.createSearchAlias("mySearchAliasView", null); ``` +See `ArangoDatabase.createView()`, `ArangoDatabase.createArangoSearch()`, and +`ArangoDatabase.createSearchAlias()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +info = db.create_view("myView", "arangosearch") +``` + +See `StandardDatabase.create_view()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_view) +for details. +{{< /tab >}} + +{{< /tabs >}} + ### Get a View -Get the View called `myView` by its name: +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired View. +2. Click **Views** in the main navigation. +3. Click the name or row of the desired View. +{{< /tab >}} +{{< tab "arangosh" >}} ```js --- name: viewUsage_02 -description: '' +description: | + Get the View called `myView` by its name: --- -view = db._view("myView"); +var view = db._view("myView"); +``` + +See `db._view()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_viewview) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/view/myView ``` +See `GET /_db/{database-name}/_api/view/{view-name}` in the +[HTTP API](../../develop/http-api/views/_index.md) for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let view = db.view("myView"); +const info = await view.get(); +``` + +See `Database.view()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#view) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +view, err := db.View(ctx, "myView") +``` + +See `DatabaseView.View()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseView) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoView view = db.view("myView"); + +ArangoSearch viewSearch = db.arangoSearch("myArangoSearchView"); +SearchAlias viewAlias = db.searchAlias("mySearchAliasView"); +``` + +See `ArangoDatabase.view(String name)`, `ArangoDatabase.arangoSearch(String name)`, +and `ArangoDatabase.searchAlias(String name)` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +info = db.view_info("myView") +``` + +See `StandardDatabase.view()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.view) +for details. +{{< /tab >}} + +{{< /tabs >}} + ### Get the View properties +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired View. +2. Click **Views** in the main navigation. +3. Click the name or row of the desired View. +{{< /tab >}} + +{{< tab "arangosh" >}} ```js --- name: viewUsage_03 description: '' --- +var view = db._view("myView"); view.properties(); ``` -### Set a View property +See `view.properties()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/view-object.md#viewpropertiesnew-properties--partialupdate) +for details. +{{< /tab >}} +{{< tab "cURL" >}} +```sh +curl http://localhost:8529/_db/mydb/_api/view/myView/properties +``` + +See `GET /_db/{database-name}/_api/view/{view-name}/properties` in the HTTP API for details: +- [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#get-the-properties-of-a-view) +- [`search-alias` View](../../develop/http-api/views/search-alias-views.md#get-information-about-a-view) +{{< /tab >}} + +{{< tab "JavaScript" >}} ```js ---- -name: viewUsage_04 -description: '' ---- -view.properties({cleanupIntervalStep: 12}); +let view = db.view("myView"); +const props = await view.properties(); ``` -### Add and remove links from a View +See `View.properties()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/view.View.html#properties) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +view, err := db.View(ctx, "myView") + +switch view.Type() { +case arangodb.ViewTypeArangoSearch: + { + viewSearch, err := view.ArangoSearchView() + props, err := viewSearch.Properties() + } +case arangodb.ViewTypeSearchAlias: + { + viewAlias, err := view.ArangoSearchViewAlias() + props, err := viewAlias.Properties() + } +default: + panic("Unsupported View type") +} +``` -Link a collection to a View: +See [`ArangoSearchView.Properties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchView) +and [`ArangoSearchViewAlias.Properties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchViewAlias) +in the go-driver v2 documentation for details. +{{< /tab >}} -```js ---- -name: viewUsage_05 -description: '' ---- -view.properties({links: {colA: {includeAllFields: true}}}); +{{< tab "Java" >}} +```java +ArangoSearch viewSearch = db.view("myArangoSearchView"); +ArangoSearchPropertiesEntity viewSearch.getProperties(); + +SearchAlias viewAlias = db.view("mySearchAliasView"); +SearchAliasPropertiesEntity viewAlias.getProperties(); ``` -Add another link to the View: +See `ArangoSearch.getProperties()` and `SearchAlias.getProperties()` +in the arangodb-java-driver documentation for details: +- [`arangosearch` View](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoSearch.html#getProperties%28%29) +- [`search-alias` View](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/SearchAlias.html#getProperties%28%29) +{{< /tab >}} + +{{< tab "Python" >}} +```py +props = db.view("myView") +``` + +See `StandardDatabase.view()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.view) +for details. +{{< /tab >}} + +{{< /tabs >}} + +### Set a View property +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired View. +2. Click **Views** in the main navigation. +3. Click the name or row of the desired View. +4. Adjust the configuration using the form or the JSON editor. +5. Click the **Save view** button. +{{< /tab >}} + +{{< tab "arangosh" >}} ```js --- -name: viewUsage_06 +name: viewUsage_04 description: '' --- -view.properties({links: {colB: {fields: {text: {}}}}}); +~db._create("coll"); +var viewSearch = db._view("myArangoSearchView"); +viewSearch.properties({ + cleanupIntervalStep: 12, + links: { + coll: { + includeAllFields: true + } + } +}, /*partialUpdate*/ true); +~db._dropView("myArangoSearchView"); + +~db.coll.ensureIndex({ type: "inverted", name: "idx", fields: [ "attr" ] }); +var viewAlias = db._view("mySearchAliasView"); +viewAlias.properties({ + indexes: [ + { collection: "coll", index: "idx" }, + ] +}, /*partialUpdate*/ true); +~viewSearch.properties({ links: { coll: null } }); +~viewAlias.properties({ indexes: [] }, false); +~db._drop("coll"); +``` + +See `view.properties()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/view-object.md#viewpropertiesnew-properties--partialupdate) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -XPATCH -d '{"cleanupIntervalStep":12,"links":{"coll":{"includeAllFields":true}}}' http://localhost:8529/_db/mydb/_api/view/myArangoSearchView/properties +curl -XPATCH -d '{"indexes":[{"collection":"coll","index":"idx"}]}' http://localhost:8529/_db/mydb/_api/view/mySearchAliasView/properties ``` -Remove the first link again: +See `PATCH /_db/{database-name}/_api/view/{view-name}/properties` in the HTTP API for details: +- [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#update-the-properties-of-an-arangosearch-view) +- [`search-alias` View](../../develop/http-api/views/search-alias-views.md#update-the-properties-of-a-search-alias-view) +{{< /tab >}} +{{< tab "JavaScript" >}} ```js ---- -name: viewUsage_07 -description: '' ---- -view.properties({links: {colA: null}}); +let view = db.view("myView"); +const info = await view.updateProperties({ + cleanupIntervalStep: 12, + links: { + coll: { + includeAllFields: true + } + } +}); +``` + +See `View.updateProperties()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/view.View.html#updateProperties) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +view1, err := db.view("myArangoSearchView") +viewSearch, err := view1.ArangoSearchView() +err = viewSearch.SetProperties(ArangoSearchViewProperties{ + CleanupIntervalStep: 12, + Links: ArangoSearchLinks{ + "coll": ArangoSearchElementProperties{ + IncludeAllFields: utils.NewType(true), + }, + }, +}) + +view2, err := db.view("mySearchAliasView") +viewAlias, err := view2.ArangoSearchViewAlias() +err := viewAlias.SetProperties(ArangoSearchAliasViewProperties{ + Indexes: []ArangoSearchAliasIndex{ + { + Collection: "coll", + Index: "idx", + }, + }, +}) +``` + +See [`ArangoSearchView.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchView) +and [`ArangoSearchViewAlias.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchViewAlias) +in the go-driver v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoSearchPropertiesOptions options = new ArangoSearchPropertiesOptions(); +options.cleanupIntervalStep(12L); +options.link(CollectionLink.on("coll") + .includeAllFields(true) +); + +ArangoSearch viewSearch = db.view("myArangoSearchView"); +ArangoSearchPropertiesEntity viewSearch.updateProperties(options); + +SearchAlias viewAlias = db.view("mySearchAliasView"); +SearchAliasPropertiesEntity viewAlias.updateProperties( + new SearchAliasPropertiesOptions() + .indexes(new SearchAliasIndex("coll", "idx")) +); +``` + +See [`ArangoSearch.updateProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoSearch.html#updateProperties%28com.arangodb.model.arangosearch.ArangoSearchPropertiesOptions%29) +and [`SearchAlias.updateProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/SearchAlias.html#updateProperties%28com.arangodb.model.arangosearch.SearchAliasPropertiesOptions%29) +in the arangodb-java-driver documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +props = db.update_view("myArangoSearchView", { + "cleanupIntervalStep": 12, + "links": { + "coll": { + "includeAllFields": True + } + } +}) + +props = db.update_view("mySearchAliasView", { + "indexes": [ + { "collection": "coll", "index": "idx"} + ] +}) ``` +See `StandardDatabase.update_view()` in the +[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.update_view) +for details. +{{< /tab >}} + +{{< /tabs >}} + ### Drop a View +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired View. +2. Click **Views** in the main navigation. +3. Click the name or row of the desired View. +4. Click the **Delete** button and confirm. +{{< /tab >}} + +{{< tab "arangosh" >}} ```js --- name: viewUsage_08 description: '' --- -~removeIgnoreCollection("colA"); -~removeIgnoreCollection("colB"); ~removeIgnoreView("myView"); +~removeIgnoreView("myArangoSearchView"); +~removeIgnoreView("mySearchAliasView"); db._dropView("myView"); -~db._drop("colA"); -~db._drop("colB"); +~db._dropView("myArangoSearchView"); +~db._dropView("mySearchAliasView"); ``` + +See `db._dropView()` in the +[JavaScript API](../../develop/javascript-api/@arangodb/view-object.md#viewdrop) +for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -XDELETE http://localhost:8529/_db/mydb/_api/view/myView +``` + +See `DELETE /_db/{database-name/_api/view/{view-name}` in the HTTP API for details: +- [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#drop-a-view) +- [`search-alias` View](../../develop/http-api/views/search-alias-views.md#drop-a-view) +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let view = db.view("myView"); +const ok = view.drop(); +``` + +See `View.drop()` in the +[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/view.View.html#drop) +for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +view, err := db.View(ctx, "myView") +err = view.Remove(ctx) +``` + +See `View.Remove()` in the +[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#View) +for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoView view = db.view("myView"); +view.drop(); +``` + +See `StandardDatabase.delete_view()` in the +[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoView.html#drop%28%29) +for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +ok = db.delete_view("myView") +``` + +See the [python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_view) +for details. +{{< /tab >}} + +{{< /tabs >}} diff --git a/site/content/3.12/develop/drivers/go.md b/site/content/3.12/develop/drivers/go.md index a8c229e27..0deb0e0fb 100644 --- a/site/content/3.12/develop/drivers/go.md +++ b/site/content/3.12/develop/drivers/go.md @@ -181,7 +181,7 @@ if err != nil { } // Open the "coll" collection -col, err := db.Collection(nil, "coll") +col, err := db.GetCollection(nil, "coll", nil) if err != nil { // Handle error } @@ -312,7 +312,7 @@ if err != nil { ```go ctx := context.Background() -col, err := db.Collection(ctx, "myCollection") +col, err := db.GetCollection(ctx, "myCollection", nil) if err != nil { // handle error } diff --git a/site/content/3.12/develop/http-api/views/_index.md b/site/content/3.12/develop/http-api/views/_index.md index 2e24d9167..78af9f921 100644 --- a/site/content/3.12/develop/http-api/views/_index.md +++ b/site/content/3.12/develop/http-api/views/_index.md @@ -20,3 +20,11 @@ the View name is `demo`, then the URL of that View is: ``` http://localhost:8529/_api/view/demo ``` + +## View types + +ArangoDB supports the following types of Views and they share endpoints in the +HTTP API but the behavior is different for each: + +- [`arangosearch` Views](arangosearch-views.md) +- [`search-alias` Views](search-alias-views.md) From ddce1c8935726b7513c50b11615e465e33954cc0 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 9 Dec 2024 13:48:10 +0100 Subject: [PATCH 2/9] Explicitly use _system database for endpoints that require it in curl examples --- site/content/3.12/develop/http-api/administration.md | 9 +++------ site/content/3.12/develop/http-api/databases.md | 8 ++++---- 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/site/content/3.12/develop/http-api/administration.md b/site/content/3.12/develop/http-api/administration.md index c9e740ae6..beb286b59 100644 --- a/site/content/3.12/develop/http-api/administration.md +++ b/site/content/3.12/develop/http-api/administration.md @@ -692,7 +692,7 @@ description: |- Query support information from a single server name: RestAdminSupportInfo --- -var url = "/_admin/support-info"; +var url = "/_db/_system/_admin/support-info"; var response = logCurlRequest("GET", url); assert(response.code === 200); assert(response.parsedBody.host !== undefined); @@ -706,7 +706,7 @@ description: |- name: RestAdminSupportInfo type: cluster --- -var url = "/_admin/support-info"; +var url = "/_db/_system/_admin/support-info"; var response = logCurlRequest("GET", url); assert(response.code === 200); assert(response.parsedBody.deployment.servers !== undefined); @@ -1752,11 +1752,8 @@ paths: description: '' name: RestEndpointGet --- -var url = "/_api/endpoint"; - +var url = "/_db/_system/_api/endpoint"; var response = logCurlRequest('GET', url); - assert(response.code === 200); - logJsonResponse(response); ``` diff --git a/site/content/3.12/develop/http-api/databases.md b/site/content/3.12/develop/http-api/databases.md index d12e72f7a..129ba1887 100644 --- a/site/content/3.12/develop/http-api/databases.md +++ b/site/content/3.12/develop/http-api/databases.md @@ -196,7 +196,7 @@ paths: description: '' name: RestDatabaseGet --- -var url = "/_api/database"; +var url = "/_db/_system/_api/database"; var response = logCurlRequest('GET', url); assert(response.code === 200); @@ -328,7 +328,7 @@ description: |- Creating a database named `example`. name: RestDatabaseCreate --- -var url = "/_api/database"; +var url = "/_db/_system/_api/database"; var name = "example"; try { db._dropDatabase(name); @@ -359,7 +359,7 @@ description: |- the newly created database. name: RestDatabaseCreateUsers --- -var url = "/_api/database"; +var url = "/_db/_system/_api/database"; var name = "mydb"; try { db._dropDatabase(name); @@ -436,7 +436,7 @@ paths: description: '' name: RestDatabaseDrop --- -var url = "/_api/database"; +var url = "/_db/_system/_api/database"; var name = "example"; db._createDatabase(name); From d52bde4025ed3ccce4d2b66a8d52050d62b68aa9 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 9 Dec 2024 14:14:47 +0100 Subject: [PATCH 3/9] Simpler collection properties examples, use _system db where necessary --- .../concepts/data-structure/collections.md | 83 ++++--------------- .../3.12/concepts/data-structure/databases.md | 10 ++- 2 files changed, 22 insertions(+), 71 deletions(-) diff --git a/site/content/3.12/concepts/data-structure/collections.md b/site/content/3.12/concepts/data-structure/collections.md index 936d09482..965c61098 100644 --- a/site/content/3.12/concepts/data-structure/collections.md +++ b/site/content/3.12/concepts/data-structure/collections.md @@ -344,6 +344,7 @@ description: '' ~db._create("products"); ~db._create("users"); db._collections(); +~db._useDatabase("_system"); ~db._dropDatabase("mydb"); ``` @@ -592,23 +593,14 @@ for details. ```js --- name: arangosh_set_collection_properties +type: cluster description: '' --- ~db._create("coll"); coll = db._collection("coll"); coll.properties({ waitForSync: true, - schema: { - rule: { - type: "object", - properties: { - attr: { - type: "number", - minimum: 10 - } - } - } - } + replicationFactor: 3 }); ~db._drop("coll"); ``` @@ -620,11 +612,11 @@ for details. {{< tab "cURL" >}} ```sh -curl http://localhost:8529/_db/mydb/_api/collection/coll/properties +curl -XPUT -d '{"waitForSync":true,"replicationFactor":3}' http://localhost:8529/_db/mydb/_api/collection/coll/properties ``` -See `GET /_db/{database-name}/_api/collection/{collection-name}/properties` in the -[HTTP API](../../develop/http-api/collections.md#get-the-properties-of-a-collection) +See `PUT /_db/{database-name}/_api/collection/{collection-name}/properties` in the +[HTTP API](../../develop/http-api/collections.md#change-the-properties-of-a-collection) for details. {{< /tab >}} @@ -633,17 +625,7 @@ for details. let coll = db.collection("coll"); const props = await coll.properties({ waitForSync: true, - schema: { - rule: { - type: "object", - properties: { - attr: { - type: "number", - minimum: 10 - } - } - } - } + replicationFactor: 3 }); ``` @@ -658,17 +640,7 @@ ctx := context.Background() coll, err := db.GetCollection(ctx, "coll", nil) err = coll.SetProperties(ctx, arangodb.SetCollectionPropertiesOptions{ WaitForSync: utils.NewType(true), - Schema: &arangodb.CollectionSchemaOptions{ - Rule: map[string]interface{} { - "type": "object", - "properties": map[string]interface{} { - "attr": map[string]interface{} { - "type": "number", - "minimum": 10, - } - } - } - } + ReplicationFactor: 3, }) ``` @@ -679,30 +651,17 @@ for details. {{< tab "Java" >}} ```java -String schemaRule = ( - "{" + - " \"type\": \"object\"," + - " \"properties\": {" + - " \"attr\": {" + - " \"type\": \"number\"," + - " \"minimum\": 10" + - " }" + - " }" + - "}"); - -CollectionPropertiesOptions props = new CollectionPropertiesOptions() - .waitForSync(true) - .schema(new CollectionSchema() - .setRule(schemaRule) - ); +CollectionPropertiesOptions options = new CollectionPropertiesOptions() + .waitForSync(true); ArangoCollection coll = db.collection("coll"); -CollectionPropertiesEntity = coll.changeProperties(props); +CollectionPropertiesEntity props = coll.changeProperties(options); ``` +{{< comment >}}TODO: setReplicationFactor not yet supported by Java driver{{< /comment >}} -See `ArangoCollection.changeProperties()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#changeProperties%28com.arangodb.model.CollectionPropertiesOptions%29) -for details. +See [`ArangoCollection.changeProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#changeProperties%28com.arangodb.model.CollectionPropertiesOptions%29) +and [`CollectionPropertiesEntity`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/entity/CollectionPropertiesEntity.html) +in the arangodb-java-driver documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -710,17 +669,7 @@ for details. coll = db.collection("coll") props = coll.configure( sync=True, - schema={ - "rule": { - "type": "object", - "properties": { - "attr": { - "type": "number", - "minimum": 10 - } - } - } - } + replication_factor=3 ) ``` diff --git a/site/content/3.12/concepts/data-structure/databases.md b/site/content/3.12/concepts/data-structure/databases.md index 5d4abb3b8..10fe6a053 100644 --- a/site/content/3.12/concepts/data-structure/databases.md +++ b/site/content/3.12/concepts/data-structure/databases.md @@ -172,7 +172,7 @@ specified database, unless specified otherwise. ```js --- name: arangosh_use_database -# _useDatabase() returns true but does this get rendered? +# TODO: _useDatabase() returns true but does this get rendered? #render: input description: '' --- @@ -272,7 +272,8 @@ a database is created. The creation of a database can therefore take a moment. ```js --- name: arangosh_create_database -render: input +# TODO: Returns true but does this get rendered? +#render: input description: '' --- var ok = db._useDatabase("_system"); // _system database context required @@ -363,6 +364,7 @@ description: '' ~db._createDatabase("mydb"); var ok = db._useDatabase("mydb"); db._properties(); +~db._useDatabase("_system"); ~db._dropDatabase("mydb"); ``` @@ -539,7 +541,7 @@ for details. curl -XDELETE http://localhost:8529/_api/database/mydb ``` -See `DELETE /_db/{database-name}/_api/database` in the +See `DELETE /_db/_system/_api/database/{database-name}` in the [HTTP API](../../develop/http-api/databases.md#drop-a-database) for details. {{< /tab >}} @@ -587,4 +589,4 @@ See `StandardDatabase.delete_database()` in the for details. {{< /tab >}} -{{< /tabs >}} \ No newline at end of file +{{< /tabs >}} From 11ec902e6ce5a1d70015c3fce3a319e11ac39d95 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 17 Dec 2024 21:49:36 +0100 Subject: [PATCH 4/9] More examples, fixes --- .../concepts/data-structure/collections.md | 254 +++--- .../3.12/concepts/data-structure/databases.md | 140 ++-- .../data-structure/documents/_index.md | 772 +++++++++++++++++- .../documents/schema-validation.md | 198 ++++- .../3.12/concepts/data-structure/views.md | 132 ++- .../index-and-search/arangosearch/_index.md | 6 +- 6 files changed, 1191 insertions(+), 311 deletions(-) diff --git a/site/content/3.12/concepts/data-structure/collections.md b/site/content/3.12/concepts/data-structure/collections.md index 965c61098..60db33931 100644 --- a/site/content/3.12/concepts/data-structure/collections.md +++ b/site/content/3.12/concepts/data-structure/collections.md @@ -143,6 +143,43 @@ attempt. Even if an insert fails, the auto-increment value is never rolled back. That means there may exist gaps in the sequence of assigned auto-increment values if inserts fails. +## Synchronous replication of collections + +Distributed ArangoDB setups offer synchronous replication, +which means that there is the option to replicate all data +automatically within an ArangoDB cluster. This is configured for sharded +collections on a per-collection basis by specifying a **replication factor**. +A replication factor of `k` means that altogether `k` copies of each shard are +kept in the cluster on `k` different servers, and are kept in sync. That is, +every write operation is automatically replicated on all copies. + +This is organized using a leader/follower model. At all times, one of the +servers holding replicas for a shard is "the leader" and all others +are "followers", this configuration is held in the Agency (see +[Cluster](../../deploy/cluster/_index.md) for details of the ArangoDB +cluster architecture). Every write operation is sent to the leader +by one of the Coordinators, and then replicated to all followers +before the operation is reported to have succeeded. The leader keeps +a record of which followers are currently in sync. In case of network +problems or a failure of a follower, a leader can and will drop a follower +temporarily after 3 seconds, such that service can resume. In due course, +the follower will automatically resynchronize with the leader to restore +resilience. + +If a leader fails, the cluster Agency automatically initiates a failover +routine after around 15 seconds, promoting one of the followers to +leader. The other followers (and the former leader, when it comes back), +automatically resynchronize with the new leader to restore resilience. +Usually, this whole failover procedure can be handled transparently +for the Coordinator, such that the user code does not even see an error +message. + +This fault tolerance comes at a cost of increased latency. +Each write operation needs an additional network roundtrip for the +synchronous replication of the followers (but all replication operations +to all followers happen concurrently). Therefore, the default replication +factor is `1`, which means no replication. + ## Collection interfaces The following sections show examples of how you can use the APIs of ArangoDB and @@ -170,9 +207,8 @@ description: '' coll = db._create("coll"); ~db._drop("coll"); ``` -See `db._create()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_createcollection-name--properties--type--options) -for details. +See [`db._create()`](../../develop/javascript-api/@arangodb/db-object.md#db_createcollection-name--properties--type--options) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -180,8 +216,8 @@ for details. curl -d '{"name":"coll"}' http://localhost:8529/_db/mydb/_api/collection ``` -See `POST /_db/{database-name}/_api/collection` in the -[HTTP API](../../develop/http-api/databases.md#create-a-database) for details. +See the [`POST /_db/{database-name}/_api/collection`](../../develop/http-api/databases.md#create-a-database) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -194,7 +230,7 @@ const info = await coll.create(); See [`Database.createCollection()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createCollection) and [`DocumentCollection.create()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#create) -in the arangojs documentation for details. +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -203,9 +239,8 @@ ctx := context.Background() coll, err := db.CreateCollection(ctx, "coll") ``` -See `DatabaseCollection.CreateCollection()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) -for details. +See [`DatabaseCollection.CreateCollection()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -217,7 +252,7 @@ CollectionEntity coll = db.collection("coll").create(); See [`ArangoDB.createCollection()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) and [`ArangoCollection.create()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#create%28%29) -in the arangodb-java-driver documentation for details. +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -225,9 +260,8 @@ in the arangodb-java-driver documentation for details. coll = db.create_collection("coll") ``` -See `StandardDatabase.create_collection()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_collection) -for details. +See [`StandardDatabase.create_collection()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_collection) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -262,9 +296,8 @@ let coll = db.coll let coll = db["coll"] ``` -See `db._collection()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_collectioncollection) -for details. +See [`db._collection()`](../../develop/javascript-api/@arangodb/db-object.md#db_collectioncollection) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -272,9 +305,8 @@ for details. curl http://localhost:8529/_db/mydb/_api/collection/coll ``` -See `GET /_db/{database-name}/_api/collection/{collection-name}` in the -[HTTP API](../../develop/http-api/collections.md#get-the-collection-information) -for details. +See the [`GET /_db/{database-name}/_api/collection/{collection-name}`](../../develop/http-api/collections.md#get-the-collection-information) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -283,9 +315,8 @@ let coll = db.collection("coll"); const info = await coll.get(); ``` -See `Database.collection()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#collection) -for details. +See [`Database.collection()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#collection) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -294,9 +325,8 @@ ctx := context.Background() coll, err := db.GetCollection(ctx, "coll", nil) ``` -See `DatabaseCollection.Collection()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) -for details. +See [`DatabaseCollection.GetCollection()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -304,9 +334,8 @@ for details. ArangoCollection coll = db.collection("coll"); ``` -See `ArangoDB.collection()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) -for details. +See [`ArangoDB.collection()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -314,9 +343,8 @@ for details. coll = db.collection("coll") ``` -See `StandardDatabase.collection()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.collection) -for details. +See [`StandardDatabase.collection()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.collection) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -348,9 +376,8 @@ db._collections(); ~db._dropDatabase("mydb"); ``` -See `db._collections()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#collections) -for details. +See [`db._collections()`](../../develop/javascript-api/@arangodb/db-object.md#collections) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -358,8 +385,8 @@ for details. curl http://localhost:8529/_db/mydb/_api/collection ``` -See `GET /_db/{database-name}/_api/collection` in the -[HTTP API](../../develop/http-api/collections.md#get-the-collection-information) for details. +See the [`GET /_db/{database-name}/_api/collection`](../../develop/http-api/collections.md#get-the-collection-information) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -367,9 +394,8 @@ See `GET /_db/{database-name}/_api/collection` in the const colls = await db.collections(); ``` -See `Database.collections()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#collections) -for details. +See [`Database.collections()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#collections) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -378,9 +404,8 @@ ctx := context.Background() colls, err := db.Collections(ctx) ``` -See `DatabaseCollection.Collections()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) -for details. +See [`DatabaseCollection.Collections()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseCollection) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -388,9 +413,8 @@ for details. Collection colls = db.getCollections(); ``` -See `ArangoDatabase.getCollections()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#getCollections%28%29) -for details. +See [`ArangoDatabase.getCollections()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#getCollections%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -398,8 +422,8 @@ for details. colls = db.collections() ``` -See `StandardDatabase.collections()` in the [python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.collections) -for details. +See [`StandardDatabase.collections()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.collections) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -414,7 +438,7 @@ for details. 2. Click **Collections** in the main navigation. 3. Click the name or row of the desired collection. 4. Go to the **Settings** tab. -5. Click the **Delete** button and confirm. +5. Click the **Delete** button and confirm the deletion. {{< /tab >}} {{< tab "arangosh" >}} @@ -428,9 +452,8 @@ description: '' db._drop("coll"); ``` -See `db._drop()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_dropcollection--options) -for details. +See [`db._drop()`](../../develop/javascript-api/@arangodb/db-object.md#db_dropcollection--options) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -438,8 +461,8 @@ for details. curl -XDELETE http://localhost:8529/_db/mydb/_api/collection/coll ``` -See `DELETE /_db/{database-name}/_api/collection/{collection-name}` in the -[HTTP API](../../develop/http-api/collections.md#drop-a-collection) for details. +See the [`DELETE /_db/{database-name}/_api/collection/{collection-name}`](../../develop/http-api/collections.md#drop-a-collection) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -448,9 +471,8 @@ let coll = db.collection("coll"); const status = await coll.drop(); ``` -See `DocumentCollection.drop()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#drop) -for details. +See [`DocumentCollection.drop()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#drop) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -460,9 +482,8 @@ coll, err := db.GetCollection(ctx, "coll", nil) err = coll.Remove(ctx) ``` -See `Collection.Remove()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) -for details. +See [`Collection.Remove()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -471,9 +492,8 @@ ArangoCollection coll = db.collection("coll"); coll.drop(); ``` -See `ArangoCollection.drop()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#drop%28%29) -for details. +See [`ArangoCollection.drop()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#drop%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -481,14 +501,13 @@ for details. ok = db.delete_collection("coll") ``` -See `StandardDatabase.delete_collection()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_collection) -for details. +See [`StandardDatabase.delete_collection()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_collection) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} -### Get collection properties +### Get the collection properties {{< tabs "interfaces" >}} @@ -508,14 +527,13 @@ name: arangosh_get_collection_properties description: '' --- ~db._create("coll"); -coll = db._collection("coll"); +var coll = db._collection("coll"); coll.properties(); ~db._drop("coll"); ``` -See `collection.properties()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) -for details. +See [`collection.properties()`](../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -523,9 +541,8 @@ for details. curl http://localhost:8529/_db/mydb/_api/collection/coll/properties ``` -See `GET /_db/{database-name}/_api/collection/{collection-name}/properties` in the -[HTTP API](../../develop/http-api/collections.md#get-the-properties-of-a-collection) -for details. +See the [`GET /_db/{database-name}/_api/collection/{collection-name}/properties`](../../develop/http-api/collections.md#get-the-properties-of-a-collection) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -534,9 +551,8 @@ let coll = db.collection("coll"); const props = await coll.properties(); ``` -See `DocumentCollection.properties()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties) -for details. +See [`DocumentCollection.properties()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -546,9 +562,8 @@ coll, err := db.GetCollection(ctx, "coll", nil) props, err := coll.Properties() ``` -See `Collection.Properties()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) -for details. +See [`Collection.Properties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -557,9 +572,8 @@ ArangoCollection coll = db.collection("coll"); CollectionPropertiesEntity = coll.getProperties(); ``` -See `ArangoCollection.getProperties()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#getProperties%28%29) -for details. +See [`ArangoCollection.getProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#getProperties%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -568,14 +582,13 @@ coll = db.collection("coll") props = coll.properties() ``` -See `Collection.properties()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.properties) -for details. +See [`Collection.properties()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.properties) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} -### Set collection properties +### Set the collection properties {{< tabs "interfaces" >}} @@ -597,7 +610,7 @@ type: cluster description: '' --- ~db._create("coll"); -coll = db._collection("coll"); +var coll = db._collection("coll"); coll.properties({ waitForSync: true, replicationFactor: 3 @@ -605,9 +618,8 @@ coll.properties({ ~db._drop("coll"); ``` -See `collection.properties()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) -for details. +See [`collection.properties()`](../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -615,9 +627,8 @@ for details. curl -XPUT -d '{"waitForSync":true,"replicationFactor":3}' http://localhost:8529/_db/mydb/_api/collection/coll/properties ``` -See `PUT /_db/{database-name}/_api/collection/{collection-name}/properties` in the -[HTTP API](../../develop/http-api/collections.md#change-the-properties-of-a-collection) -for details. +See the [`PUT /_db/{database-name}/_api/collection/{collection-name}/properties`](../../develop/http-api/collections.md#change-the-properties-of-a-collection) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -629,9 +640,8 @@ const props = await coll.properties({ }); ``` -See `DocumentCollection.properties()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties.properties-2) -for details. +See [`DocumentCollection.properties()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties.properties-2) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -644,9 +654,8 @@ err = coll.SetProperties(ctx, arangodb.SetCollectionPropertiesOptions{ }) ``` -See `Collection.SetProperties()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) -for details. +See [`Collection.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -661,7 +670,7 @@ CollectionPropertiesEntity props = coll.changeProperties(options); See [`ArangoCollection.changeProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#changeProperties%28com.arangodb.model.CollectionPropertiesOptions%29) and [`CollectionPropertiesEntity`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/entity/CollectionPropertiesEntity.html) -in the arangodb-java-driver documentation for details. +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -673,49 +682,8 @@ props = coll.configure( ) ``` -See `Collection.configure()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.configure) -for details. +See [`Collection.configure()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.configure) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} - -### Synchronous replication of collections - -Distributed ArangoDB setups offer synchronous replication, -which means that there is the option to replicate all data -automatically within an ArangoDB cluster. This is configured for sharded -collections on a per-collection basis by specifying a **replication factor**. -A replication factor of `k` means that altogether `k` copies of each shard are -kept in the cluster on `k` different servers, and are kept in sync. That is, -every write operation is automatically replicated on all copies. - -This is organized using a leader/follower model. At all times, one of the -servers holding replicas for a shard is "the leader" and all others -are "followers", this configuration is held in the Agency (see -[Cluster](../../deploy/cluster/_index.md) for details of the ArangoDB -cluster architecture). Every write operation is sent to the leader -by one of the Coordinators, and then replicated to all followers -before the operation is reported to have succeeded. The leader keeps -a record of which followers are currently in sync. In case of network -problems or a failure of a follower, a leader can and will drop a follower -temporarily after 3 seconds, such that service can resume. In due course, -the follower will automatically resynchronize with the leader to restore -resilience. - -If a leader fails, the cluster Agency automatically initiates a failover -routine after around 15 seconds, promoting one of the followers to -leader. The other followers (and the former leader, when it comes back), -automatically resynchronize with the new leader to restore resilience. -Usually, this whole failover procedure can be handled transparently -for the Coordinator, such that the user code does not even see an error -message. - -This fault tolerance comes at a cost of increased latency. -Each write operation needs an additional network roundtrip for the -synchronous replication of the followers (but all replication operations -to all followers happen concurrently). Therefore, the default replication -factor is `1`, which means no replication. - -For details on how to switch on synchronous replication for a collection, -see the [`db` object](../../develop/javascript-api/@arangodb/db-object.md#db_createcollection-name--properties--type--options). diff --git a/site/content/3.12/concepts/data-structure/databases.md b/site/content/3.12/concepts/data-structure/databases.md index 10fe6a053..b89763a48 100644 --- a/site/content/3.12/concepts/data-structure/databases.md +++ b/site/content/3.12/concepts/data-structure/databases.md @@ -172,8 +172,6 @@ specified database, unless specified otherwise. ```js --- name: arangosh_use_database -# TODO: _useDatabase() returns true but does this get rendered? -#render: input description: '' --- ~db._createDatabase("mydb"); @@ -183,7 +181,7 @@ db._useDatabase("mydb"); ``` See [`db._useDatabase()`](../../develop/javascript-api/@arangodb/db-object.md#db_usedatabasename) -in the JavaScript API for details. +in the _JavaScript API_ for details. It is also possible to specify a database name when invoking arangosh. For this purpose, use the `--server.database` startup option: @@ -203,7 +201,7 @@ curl http://localhost:8529/_db/mydb/... ``` See [Addresses of databases](../../develop/http-api/databases.md#addresses-of-databases) -in the HTTP API for details. +in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -217,7 +215,7 @@ const otherDb = myDb.database("other"); See [`new Database()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#constructor) and [`Database.database()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#database) -in the arangojs documentation for details. +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -226,9 +224,8 @@ ctx := context.Background() db, err := client.GetDatabase(ctx, "mydb") ``` -See `ClientDatabase.GetDatabase()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) -for details. +See [`ClientDatabase.GetDatabase()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -236,9 +233,8 @@ for details. ArangoDatabase db = arangoDB.db("mydb"); ``` -See `ArangoDB.db()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) -for details. +See [`ArangoDB.db()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#db%28java.lang.String%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -246,9 +242,8 @@ for details. db = client.db('mydb') ``` -See `ArangoClient.db()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.client.ArangoClient.db) -for details. +See [`ArangoClient.db()`](https://docs.python-arango.com/en/main/specs.html#arango.client.ArangoClient.db) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -272,8 +267,6 @@ a database is created. The creation of a database can therefore take a moment. ```js --- name: arangosh_create_database -# TODO: Returns true but does this get rendered? -#render: input description: '' --- var ok = db._useDatabase("_system"); // _system database context required @@ -281,9 +274,8 @@ db._createDatabase("mydb"); ~db._dropDatabase("mydb"); ``` -See `db._createDatabase()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_createdatabasename--options--users) -for details. +See [`db._createDatabase()`](../../develop/javascript-api/@arangodb/db-object.md#db_createdatabasename--options--users) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -291,8 +283,8 @@ for details. curl -d '{"name":"mydb"}' http://localhost:8529/_api/database ``` -See `POST /_db/_system/_api/database` in the -[HTTP API](../../develop/http-api/databases.md#create-a-database) for details. +See the [`POST /_db/_system/_api/database`](../../develop/http-api/databases.md#create-a-database) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -300,9 +292,8 @@ See `POST /_db/_system/_api/database` in the const info = await db.createDatabase("mydb"); ``` -See `Database.createDatabase()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createDatabase) -for details. +See [`Database.createDatabase()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createDatabase) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -311,9 +302,8 @@ ctx := context.Background() db, err := client.CreateDatabase(ctx, "mydb") ``` -See `ClientDatabase.CreateDatabase()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) -for details. +See [`ClientDatabase.CreateDatabase()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -326,7 +316,7 @@ Boolean ok = db.create(); See [`ArangoDB.createDatabase()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#createDatabase%28java.lang.String%29) and [`ArangoDatabase.create()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#create%28%29) -in the arangodb-java-driver documentation for details. +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -336,9 +326,8 @@ ok = sys_db.create_database("mydb") db = client.db("mydb") ``` -See `StandardDatabase.create_database()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_database) -for details. +See [`StandardDatabase.create_database()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_database) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -368,9 +357,8 @@ db._properties(); ~db._dropDatabase("mydb"); ``` -See `db._properties()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_properties) -for details. +See [`db._properties()`](../../develop/javascript-api/@arangodb/db-object.md#db_properties) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -378,8 +366,8 @@ for details. curl http://localhost:8529/_db/mydb/_api/database/current ``` -See `GET /_db/{database-name}/_api/database/current` in the -[HTTP API](../../develop/http-api/databases.md#get-information-about-the-current-database) for details. +See the [`GET /_db/{database-name}/_api/database/current`](../../develop/http-api/databases.md#get-information-about-the-current-database) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -388,9 +376,8 @@ const myDb = db.database("mydb"); const info = await myDb.get(); ``` -See `Database.get()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#get) -for details. +See [`Database.get()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#get) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -400,9 +387,8 @@ db, err := client.GetDatabase(ctx, "mydb", nil) info, err := db.Info(ctx) ``` -See `Database.GetDatabase()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Database) -for details. +See [`Database.GetDatabase()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Database) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -411,9 +397,8 @@ ArangoDatabase db = arangoDB.db("mydb"); DatabaseEntity info = db.getInfo(); ``` -See `ArangoDatabase.getInfo()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#getInfo%28%29) -for details. +See [`ArangoDatabase.getInfo()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#getInfo%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -422,9 +407,8 @@ db = client.db("mydb") info = db.properties() ``` -See `StandardDatabase.properties()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.properties) -for details. +See [`StandardDatabase.properties()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.properties) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -451,9 +435,8 @@ db._databases(); ~db._dropDatabase("mydb"); ``` -See `db._databases()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_databases) -for details. +See [`db._databases()`](../../develop/javascript-api/@arangodb/db-object.md#db_databases) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -461,8 +444,8 @@ for details. curl http://localhost:8529/_api/database ``` -See `GET /_db/_system/_api/database` in the -[HTTP API](../../develop/http-api/databases.md#list-all-databases) for details. +See the [`GET /_db/_system/_api/database`](../../develop/http-api/databases.md#list-all-databases) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -470,9 +453,8 @@ See `GET /_db/_system/_api/database` in the const dbNames = await db.databases(); ``` -See `Database.databases()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#databases) -for details. +See [`Database.databases()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#databases) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -481,9 +463,8 @@ ctx := context.Background() dbs, err := client.Databases(ctx) ``` -See `ClientDatabase.Databases()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) -for details. +See [`ClientDatabase.Databases()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ClientDatabase) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -491,9 +472,8 @@ for details. Collection dbNames = arangoDB.getDatabases(); ``` -See `ArangoDB.getDatabases()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#getDatabases%28%29) -for details. +See [`ArangoDB.getDatabases()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDB.html#getDatabases%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -502,9 +482,8 @@ sys_db = client.db("_system") # _system database context required db_names = sys_db.databases() ``` -See `StandardDatabase.databases()` the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.databases) -for details. +See [`StandardDatabase.databases()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.databases) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -517,7 +496,7 @@ for details. 1. Switch to the `_system` database. 2. Click **Databases** in the main navigation. 3. Click the name or the row of the database you want to delete. -4. Click the **Delete** button and confirm. +4. Click the **Delete** button and confirm the deletion. {{< /tab >}} {{< tab "arangosh" >}} @@ -531,9 +510,8 @@ var ok = db._useDatabase("_system"); // _system database context required db._dropDatabase("mydb"); ``` -See `db._dropDatabase()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_dropdatabasename) -for details. +See [`db._dropDatabase()`](../../develop/javascript-api/@arangodb/db-object.md#db_dropdatabasename) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -541,8 +519,8 @@ for details. curl -XDELETE http://localhost:8529/_api/database/mydb ``` -See `DELETE /_db/_system/_api/database/{database-name}` in the -[HTTP API](../../develop/http-api/databases.md#drop-a-database) for details. +See the [`DELETE /_db/_system/_api/database/{database-name}`](../../develop/http-api/databases.md#drop-a-database) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -550,9 +528,8 @@ See `DELETE /_db/_system/_api/database/{database-name}` in the const ok = await db.dropDatabase("mydb"); ``` -See `Database.dropDatabase()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#dropDatabase) -for details. +See [`Database.dropDatabase()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#dropDatabase) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -562,9 +539,8 @@ db, err := client.GetDatabase(ctx, "mydb", nil) err = db.Remove(ctx) ``` -See `Database.Remove()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Database) -for details. +See [`Database.Remove()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Database) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -573,9 +549,8 @@ ArangoDatabase db = arangoDB.db("mydb"); Boolean ok = db.drop(); ``` -See `ArangoDatabase.drop()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#drop%28%29) -for details. +See [`ArangoDatabase.drop()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#drop%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -584,9 +559,8 @@ sys_db = client.db("_system") # _system database context required ok = sys_db.delete_database("mydb") ``` -See `StandardDatabase.delete_database()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_database) -for details. +See [`StandardDatabase.delete_database()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_database) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} diff --git a/site/content/3.12/concepts/data-structure/documents/_index.md b/site/content/3.12/concepts/data-structure/documents/_index.md index b394b377a..b4c631b0e 100644 --- a/site/content/3.12/concepts/data-structure/documents/_index.md +++ b/site/content/3.12/concepts/data-structure/documents/_index.md @@ -251,11 +251,771 @@ following naming constraints are not violated: - Attribute names are case-sensitive. -## Documents API +## Document interfaces -You can use the JavaScript interface for documents to handle documents from -the _arangosh_ command-line tool, as well as in server-side JavaScript code -like Foxx microservices. -See the [_collection_ object](../../../develop/javascript-api/@arangodb/collection-object.md#documents) +The following sections show examples of how you can use the APIs of ArangoDB and +the official drivers, as well as the built-in web interface, to perform common +operations related to documents. For less common operations and other drivers, +see the corresponding reference documentation. -For other languages see the corresponding language API. +### Create documents + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Click **Collections** in the main navigation. +2. Click the name or row of the desired collection. +3. Go to the **Content** tab. +4. Click the plus icon on the right-hand side. +5. In the **Create Document** dialog, optionally enter a document key (**_key**) + and a **Document body**. +6. Click the **Create** button. + +You can also create documents with AQL queries using the +[`INSERT` operation](../../../aql/high-level-operations/insert.md) +in the **Queries** section. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_create_documents +description: '' +--- +~db._create("coll"); +var coll = db._collection("coll"); + +// Single document +coll.insert({ + _key: "the-document-key", + name: "ArangoDB", + tags: ["graph", "database", "NoSQL"], + scalable: true, + company: { + name: "ArangoDB Inc.", + founded: 2015 + } +}); + +// Multiple documents +coll.insert([ { _key: "one" }, { _key: "two" }, { _key: "three" } ]); +~db._drop("coll"); +``` +See [`collection.insert()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectioninsertdata--options) +(and the `collection.save()` alias) in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +# Single document +curl -d '{"_key":"the-document-key","name":"ArangoDB","tags":["graph","database","NoSQL"],"scalable":true,"company":{"name":"ArangoDB Inc.","founded":2015}}' http://localhost:8529/_db/mydb/_api/document/coll + +# Multiple documents +curl -d '[ {"_key":"one"}, {"_key":"two"}, {"_key":"three"} ]' http://localhost:8529/_db/mydb/_api/document/coll +``` + +See the `POST /_db/{database-name}/_api/document/{collection-name}` endpoint for +[a single document](../../../develop/http-api/documents.md#create-a-document) +and [multiple documents](../../../develop/http-api/documents.md#create-multiple-documents) +in the _HTTP API_ for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); + +// Single document +const result = await coll.save({ + _key: "the-document-key", + name: "ArangoDB", + tags: ["graph", "database", "NoSQL"], + scalable: true, + company: { + name: "ArangoDB Inc.", + founded: 2015 + } +}); + +// Multiple documents +const results = await coll.saveAll([ { _key: "one" }, { _key: "two" }, { _key: "three" } ]); +``` + +See [`DocumentCollection.save()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#save) +and [`DocumentCollection.saveAll()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#saveAll) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll") + +// Single document +coll.CreateDocument(map[string]interface{} { + "_key": "the-document-key", + "name": "ArangoDB", + "tags": []interface{} { "graph", "database", "NoSQL" }, + "scalable": true, + "company": map[string]interface{} { + "name": "ArangoDB Inc.", + "founded": 2015, + }, +}) + +// Multiple documents +coll.CreateDocuments([]interface{} { + map[string]interface{} { "_key": "one" }, + map[string]interface{} { "_key": "two" }, + map[string]interface{} { "_key": "three" }, +}) +``` + +See [`CollectionDocumentCreate.CreateCollection()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentCreate) +in the _go-driver_ v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +CollectionEntity coll = db.collection("coll"); + +// Single document +coll.insertDocument(new BaseDocument("the-document-key") + .addAttribute("name", "ArangoDB") + .addAttribute("tags", [ "graph", "database", "NoSQL" ]) + .addAttribute("scalable", true) + .addAttribute("company", new Map() + .put("name", "ArangoDB Inc.") + .put("founded", 2015) + ) + .addAttribute("name", "ArangoDB") +); + +// Multiple documents +coll.insertDocuments([ + new BaseDocument("one"), + new BaseDocument("two"), + new BaseDocument("three") +]); +``` + +See [`ArangoCollection.insertDocument()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#insertDocument%28java.lang.Object%29) +and [`ArangoCollection.insertDocuments()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#insertDocuments%28java.lang.Iterable%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.get_collection("coll") + +# Single document +meta = coll.insert({ + "_key": "the-document-key", + "name": "ArangoDB", + "tags": { "graph", "database", "NoSQL" }, + "scalable": True, + "company": { + "name": "ArangoDB Inc.", + "founded": 2015, + } +}) + +# Multiple documents +meta = coll.insert_many([ + { "_key": "one" }, + { "_key": "two" }, + { "_key": "three" } +]) +``` + +See [`StandardCollection.insert()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.insert) +and [`StandardCollection.insert_many()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.insert_many) +in the _python-arango_ documentation for details. +{{< /tab >}} + +{{< /tabs >}} + +### Get documents + +{{< comment >}}TODO: Dirty reads?{{< /comment >}} + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Click **Collections** in the main navigation. +2. Click the name or row of the desired collection. +3. Go to the **Content** tab. +4. You may click the filter icon to filter and sort by document attributes. +5. Click a row to open the full document. + +You can also retrieve documents with AQL queries using in the **Queries** section. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_get_documents +description: '' +--- +~db._create("coll"); +var coll = db._collection("coll"); + +~coll.insert({ +~ _key: "the-document-key", +~ name: "ArangoDB", +~ tags: ["graph", "database", "NoSQL"], +~ scalable: true, +~ company: { +~ name: "ArangoDB Inc.", +~ founded: 2015 +~ } +~}); +~coll.insert([ { _key: "one" }, { _key: "two" }, { _key: "three" } ]); + +// Single document +coll.document("the-document-key"); + +// Multiple documents +coll.document([ "one", "two", { _key: "three" } ]); + +~db._drop("coll"); +``` + +See [`collection.document()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectiondocumentobject--options) +in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +# Single document +curl http://localhost:8529/_db/mydb/_api/document/coll/the-document-key + +# Multiple documents +# Note the PUT method in combination with the onlyget=true query parameter +curl -XPUT -d '["one","two",{"_key":"three"}]' http://localhost:8529/_db/mydb/_api/document/coll?onlyget=true +``` + +See the following endpoints in the _HTTP API_ for details: +- [`GET /_db/{database-name}/_api/document/{collection-name}/{document-key}`](../../../develop/http-api/documents.md#get-a-document) +- [`PUT /_db/{database-name}/_api/document/{collection-name}?onlyget=true`](../../../develop/http-api/documents.md#get-multiple-documents) +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); + +// Single document +const result = await coll.document("the-document-key"); + +// Multiple documents +const results = await coll.documents(["one", "two", { _key: "three" } ]); +``` + +See [`DocumentCollection.document()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#document) +and [`DocumentCollection.documents()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#documents) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) + +// Single document +var doc map[string]interface{}{} +meta, err := coll.ReadDocument(ctx, "the-document-key", &doc) + +// Multiple documents +result, err := coll.ReadDocuments(ctx, []string{ "one", "two", "three" }) +for { + meta, err := result.Read(&doc) + if shared.IsNoMoreDocuments(err) { + break + } +} +``` + +See [`CollectionDocumentRead.ReadDocument()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentRead) +and [`CollectionDocumentRead.ReadDocuments()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentRead) +in the _go-driver_ v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); + +// Single document +BaseDocument doc = coll.getDocument("the-document-key", BaseDocument.class); + +// Multiple documents +for (doc : coll.getDocuments(["one", "two", "three"], BaseDocument.class)) { + // ... +} +``` + +See [`ArangoCollection.getDocument()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#getDocument%28java.lang.String,java.lang.Class%29) +and [`ArangoCollection.getDocuments()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#getDocuments%28java.lang.Iterable,java.lang.Class%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") + +# Single document +doc = coll.get("the-document-key") + +# Multiple documents +docs = coll.get_many(["one", "two", { "_key": "three" } ]) +``` + +See [`StandardCollection.get()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.get) +and [`StandardCollection.get_many()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.get_many) +in the _python-arango_ documentation for details. +{{< /tab >}} + +{{< /tabs >}} + +### Update documents + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Click **Collections** in the main navigation. +2. Click the name or row of the desired collection. +3. Go to the **Content** tab. +4. You may click the filter icon to filter and sort by document attributes. +5. Click a row to open the full document. +6. Adjust the document in the editor. +7. Click the **Save** button at the bottom. + +You can also partially modify documents with AQL queries using the +[`UPDATE` operation](../../../aql/high-level-operations/update.md) +in the **Queries** section. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_update_documents +description: '' +--- +~db._create("coll"); +var coll = db._collection("coll"); + +~coll.insert({ +~ _key: "the-document-key", +~ name: "ArangoDB", +~ tags: ["graph", "database", "NoSQL"], +~ scalable: true, +~ company: { +~ name: "ArangoDB Inc.", +~ founded: 2015 +~ } +~}); +~coll.insert([ { _key: "one" }, { _key: "two" }, { _key: "three" } ]); + +coll.update("the-document-key", { logo: "avocado" }, { returnNew: true }); +coll.update([ "one", "two", { _key: "three" } ], [ { val: 1 }, { val: 2 }, { val: 3 } ]); +~db._drop("coll"); +``` + +See [`collection.update()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectionupdatedocument-data--options) +in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +# Single document +curl -XPATCH -d '{"logo":"avocado"}' http://localhost:8529/_db/mydb/_api/document/coll/the-document-key?returnNew=true + +# Multiple documents +curl -XPATCH -d '[{"_key":"one","val":1},{"_key":"two","val":2},{"_key":"three","val":3}]' http://localhost:8529/_db/mydb/_api/document/coll +``` + +See the following endpoints in the _HTTP API_ for details: +- [`PATCH /_db/{database-name}/_api/document/{collection-name}/{document-key}`](../../../develop/http-api/documents.md#update-a-document) +- [`PATCH /_db/{database-name}/_api/document/{collection-name}`](../../../develop/http-api/documents.md#update-multiple-documents) +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); + +// Single document +const result = await coll.update("the-document-key", { logo: "avocado" }, { returnNew: true }); + +// Multiple documents +const results = await coll.updateAll([ { _key: "one", val: 1 }, { _key: "two", val: 2 }, { _key: "three", val: 3 } ]); +``` + +See [`DocumentCollection.update()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#update) +and [`DocumentCollection.updateAll()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#updateAll) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) + +// Single document +var doc map[string]interface{}{} +result, err := coll.UpdateDocumentWithOptions(ctx, "the-document-key", &arangodb.CollectionDocumentUpdateOptions{ + NewObject: &doc +}) +fmt.Printf("New document: %+v\n", doc) + +// Multiple documents +newDocs := []interface{} { + map[string]interface{} { "_key": "one", "val": 1 }, + map[string]interface{} { "_key": "two", "val", 2 }, + map[string]interface{} { "_key": "three", "val", 3 }, +} +result, err := coll.UpdateDocuments(ctx, newDocs) +for { + meta, err := result.Read(&result) + if shared.IsNoMoreDocuments(err) { + break + } + fmt.Printf("Updated document metadata: %+v\n", meta) +} +``` + +See [`CollectionDocumentRead.UpdateDocumentWithOptions()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentUpdate) +and [`CollectionDocumentRead.UpdateDocuments()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentUpdate) +in the _go-driver_ v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); + +// Single document +DocumentUpdateEntity result = coll.updateDocument("the-document-key", + new BaseDocument("the-document-key") + .addAttribute("logo", "avocado"), + new DocumentUpdateOptions() + .returnNew(true), + BaseDocument.class); + +// Multiple documents +for (MultiDocumentEntity> result : coll.updateDocuments([ + new BaseDocument("one").addAttribute("val", 1), + new BaseDocument("two").addAttribute("val", 2), + new BaseDocument("three").addAttribute("val", 3) +])) { + // ... +} +``` + +See [`ArangoCollection.updateDocument()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#updateDocument%28java.lang.String,java.lang.Object,com.arangodb.model.DocumentUpdateOptions,java.lang.Class%29) +and [`ArangoCollection.updateDocuments()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#updateDocuments%28java.lang.Iterable%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") + +# Single document +meta = coll.update({ "_key": "the-document-key", "logo": "avocado" }, return_new=True) + +# Multiple documents +meta = coll.update_many([ + { "_key": "one", "val": 1 }, + { "_key": "two", "val": 2 }, + { "_key": "three", "val": 3 } +]) +``` + +See [`StandardCollection.update()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.update) +and [`StandardCollection.update_many()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.update_many) +in the _python-arango_ documentation for details. +{{< /tab >}} + +{{< /tabs >}} + +### Replace documents + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Click **Collections** in the main navigation. +2. Click the name or row of the desired collection. +3. Go to the **Content** tab. +4. You may click the filter icon to filter and sort by document attributes. +5. Click a row to open the full document. +6. Delete the document content in the editor and set new attributes. +7. Click the **Save** button at the bottom. + +You can also set new content for documents with AQL queries using the +[`REPLACE` operation](../../../aql/high-level-operations/replace.md) +in the **Queries** section. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_replace_documents +description: '' +--- +~db._create("coll"); +var coll = db._collection("coll"); + +~coll.insert({ +~ _key: "the-document-key", +~ name: "ArangoDB", +~ tags: ["graph", "database", "NoSQL"], +~ scalable: true, +~ company: { +~ name: "ArangoDB Inc.", +~ founded: 2015 +~ } +~}); +~coll.insert([ { _key: "one" }, { _key: "two" }, { _key: "three" } ]); + +coll.replace("the-document-key", { logo: "avocado" }, { returnNew: true }); +coll.replace([ "one", "two", { _key: "three" } ], [ { val: 1 }, { val: 2 }, { val: 3 } ]); +~db._drop("coll"); +``` + +See [`collection.replace()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectionreplacedocument-data--options) +in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +# Single document +curl -XPUT -d '{"logo":"avocado"}' http://localhost:8529/_db/mydb/_api/document/coll/the-document-key?returnNew=true + +# Multiple documents +curl -XPUT -d '[{"_key":"one","val":1},{"_key":"two","val":2},{"_key":"three","val":3}]' http://localhost:8529/_db/mydb/_api/document/coll +``` + +See the following endpoints in the _HTTP API_ for details: +- [`PUT /_db/{database-name}/_api/document/{collection-name}/{document-key}`](../../../develop/http-api/documents.md#replace-a-document) +- [`PUT /_db/{database-name}/_api/document/{collection-name}`](../../../develop/http-api/documents.md#replace-multiple-documents) +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); + +// Single document +const result = await coll.replace("the-document-key", { logo: "avocado" }, { returnNew: true }); + +// Multiple documents +const results = await coll.replaceAll([ { _key: "one", val: 1 }, { _key: "two", val: 2 }, { _key: "three", val: 3 } ]); +``` + +See [`DocumentCollection.replace()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#replace) +and [`DocumentCollection.replaceAll()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#replaceAll) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) + +// Single document +var doc map[string]interface{}{} +result, err := coll.ReplaceDocumentWithOptions(ctx, "the-document-key", &arangodb.CollectionDocumentUpdateOptions{ + NewObject: &doc +}) +fmt.Printf("New document: %+v\n", doc) + +// Multiple documents +newDocs := []interface{} { + map[string]interface{} { "_key": "one", "val": 1 }, + map[string]interface{} { "_key": "two", "val", 2 }, + map[string]interface{} { "_key": "three", "val", 3 }, +} +result, err := coll.UpdateDocuments(ctx, newDocs) +for { + meta, err := result.Read(&result) + if shared.IsNoMoreDocuments(err) { + break + } + fmt.Printf("Replaced document metadata: %+v\n", meta) +} +``` + +See [`CollectionDocumentRead.ReplaceDocumentWithOptions()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentReplace) +and [`CollectionDocumentRead.ReplaceDocuments()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentReplace) +in the _go-driver_ v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); + +// Single document +DocumentUpdateEntity result = coll.replaceDocument("the-document-key", + new BaseDocument("the-document-key") + .addAttribute("logo", "avocado"), + new DocumentUpdateOptions() + .returnNew(true), + BaseDocument.class); + +// Multiple documents +for (MultiDocumentEntity> result : coll.replaceDocuments([ + new BaseDocument("one").addAttribute("val", 1), + new BaseDocument("two").addAttribute("val", 2), + new BaseDocument("three").addAttribute("val", 3) +])) { + // ... +} +``` + +See [`ArangoCollection.replaceDocument()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#replaceDocument%28java.lang.String,java.lang.Object,com.arangodb.model.DocumentUpdateOptions,java.lang.Class%29) +and [`ArangoCollection.replaceDocuments()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#replaceDocuments%28java.lang.Iterable%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") + +# Single document +meta = coll.replace({ "_key": "the-document-key", "logo": "avocado" }, return_new=True) + +# Multiple documents +meta = coll.replace_many([ + { "_key": "one", "val": 1 }, + { "_key": "two", "val": 2 }, + { "_key": "three", "val": 3 } +]) +``` + +See [`StandardCollection.replace()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.replace) +and [`StandardCollection.replace_many()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.replace_many) +in the _python-arango_ documentation for details. +{{< /tab >}} + +{{< /tabs >}} + +### Remove documents + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. Click **Collections** in the main navigation. +2. Click the name or row of the desired collection. +3. Go to the **Content** tab. +4. You may click the filter icon to filter and sort by document attributes. +5. In the row of the document you want to delete, you can click the minus icon + on the right-hand side and confirm the deletion. +6. Alternatively, click a row to open the full document, then click the + **Delete** button at the bottom and confirm the deletion. + +You can also delete documents with AQL queries using the +[`REMOVE` operation](../../../aql/high-level-operations/remove.md) +in the **Queries** section. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_delete_documents +description: '' +--- +~db._create("coll"); +var coll = db._collection("coll"); +~coll.insert({ _key: "the-document-key" }); +~coll.insert([ { _key: "one" }, { _key: "two" }, { _key: "three" } ]); +coll.remove("the-document-key"); +coll.remove([ "one", "two", { _key: "three" } ]); +~db._drop("coll"); +``` + +See [`collection.remove()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectionremoveobject) +in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +# Single document +curl -XDELETE http://localhost:8529/_db/mydb/_api/document/coll/the-document-key + +# Multiple documents +curl -XDELETE -d '["one","two",{"_key":"three"}]' http://localhost:8529/_db/mydb/_api/document/coll +``` + +See the following endpoints in the _HTTP API_ for details: +- [`DELETE /_db/{database-name}/_api/document/{collection-name}/{document-key}`](../../../develop/http-api/documents.md#remove-a-document) +- [`DELETE /_db/{database-name}/_api/document/{collection-name}`](../../../develop/http-api/documents.md#remove-multiple-documents) +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); + +// Single document +const result = await coll.remove("the-document-key"); + +// Multiple documents +const results = await coll.removeAll(["one", "two", { _key: "three" } ]); +``` + +See [`DocumentCollection.remove()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#remove) +and [`DocumentCollection.removeAll()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#removeAll) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) + +// Single document +result, err := coll.DeleteDocument(ctx, "the-document-key") + +// Multiple documents +result, err = coll.DeleteDocuments(ctx, []string{ "one", "two", "three" }) +``` + +See the following functions +in the [_go-driver_ v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#CollectionDocumentDelete) +for details: +- `CollectionDocumentRead.DeleteDocument()` +- `CollectionDocumentRead.DeleteDocumentsWithOptions()` +- `CollectionDocumentRead.DeleteDocument()` +- `CollectionDocumentRead.DeleteDocumentsWithOptions()` +{{< /tab >}} + +{{< tab "Java" >}} +```java +ArangoCollection coll = db.collection("coll"); + +// Single document +DocumentDeleteEntity result = coll.deleteDocument("the-document-key"); + +// Multiple documents +for (MultiDocumentEntity> result : coll.deleteDocuments(["one", "two", "three"])) { + // ... +} +``` + +See [`ArangoCollection.deleteDocument()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#deleteDocument%28java.lang.String%29) +and [`ArangoCollection.deleteDocuments()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#getDocuments%28java.lang.Iterable,java.lang.Class%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") + +# Single document +meta = coll.delete("the-document-key") + +# Multiple documents +meta = coll.delete_many(["one", "two", { "_key": "three" } ]) +``` + +See [`StandardCollection.delete()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.delete) +and [`StandardCollection.delete_many()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.StandardCollection.delete_many) +in the _python-arango_ documentation for details. +{{< /tab >}} + +{{< /tabs >}} diff --git a/site/content/3.12/concepts/data-structure/documents/schema-validation.md b/site/content/3.12/concepts/data-structure/documents/schema-validation.md index d54761bda..c34ab7ab9 100644 --- a/site/content/3.12/concepts/data-structure/documents/schema-validation.md +++ b/site/content/3.12/concepts/data-structure/documents/schema-validation.md @@ -26,32 +26,224 @@ object with the following attributes: `rule`, `level` and `message`. - `level` controls when the validation is applied. - `message` sets the message that is used when validation fails. +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](databases.md#set-the-database-context) + that contains the desired collection. +2. Click **Collections** in the main navigation. +3. Click the name or row of the desired collection. +4. Go to the **Schema** tab. +5. Enter the desired JSON Schema. Example: + ```json + { + "rule": { + "type": "object", + "properties": { + "nums": { + "type": "array", + "items": { + "type": "number", + "maximum": 6 + } + } + }, + "additionalProperties": { "type": "string" }, + "required": [ "nums" ] + }, + "level": "moderate", + "message": "The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string." + } + ``` +6. Click the **Save** button. +{{< /tab >}} + +{{< tab "arangosh" >}} ```js +--- +name: arangosh_set_collection_properties +description: '' +--- var schema = { rule: { - properties: { nums: { type: "array", items: { type: "number", maximum: 6 } } }, + type: "object", + properties: { + nums: { + type: "array", + items: { + type: "number", + maximum: 6 + } + } + }, additionalProperties: { type: "string" }, required: ["nums"] }, level: "moderate", - message: "The document does not contain an array of numbers in attribute 'nums', or one of the numbers is greater than 6." + message: "The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string." }; /* Create a new collection with schema */ -db._create("schemaCollection", { "schema": schema }); +var coll = db._create("schemaCollection", { "schema": schema }); /* Update the schema of an existing collection */ db.schemaCollection.properties({ "schema": schema }); +~addIgnoreCollection(coll.name()); ``` +{{< comment >}}TODO: Move disabling/removing schema to separate headline?{{< /comment >}} To remove an existing schema from a collection, a schema value of either `null` or `{}` (empty object) can be stored: ```js +~var coll = db._collection("schemaCollection"); /* Remove the schema of an existing collection */ db.schemaCollection.properties({ "schema": null }); +~removeIgnoreCollection(coll.name()); +~db._drop(coll.name()); +``` + +See [`collection.properties()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) +in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -XPUT -d '{"schema":{"rule":{"type":"object","properties":{"nums":{"type":"array","items":{"type":"number","minimum":6}}},"additionalProperties":{"type":"string"},"required":["nums"]},"level":"moderate","message":"The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string."}}' http://localhost:8529/_db/mydb/_api/collection/coll/properties +``` + +See the [`GET /_db/{database-name}/_api/collection/{collection-name}/properties`](../../develop/http-api/collections.md#get-the-properties-of-a-collection) +endpoint in the _HTTP API_for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); +const props = await coll.properties({ + schema: { + rule: { + type: "object", + properties: { + nums: { + type: "array", + items: { + type: "number", + minimum: 6 + } + } + }, + additionalProperties: { type: "string" }, + required: ["nums"] + }, + level: "moderate", + message: "The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string." + } +}); +``` + +See [`DocumentCollection.properties()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties.properties-2) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) +err = coll.SetProperties(ctx, arangodb.SetCollectionPropertiesOptions{ + Schema: &arangodb.CollectionSchemaOptions{ + Rule: map[string]interface{} { + "type": "object", + "properties": map[string]interface{} { + "nums": map[string]interface{} { + "type": "array", + "items": map[string]interface{} { + "type": "number", + "minimum": 6 + }, + }, + }, + "additionalProperties": map[string]interface{} { + "type": "string", + }, + "required": []string { + "nums", + } + }, + Level: "moderate", + Message: `The document does not contain an array of numbers in attribute "nums", one of the numbers is greater than 6, or another top-level attribute is not a string.`, + } +}) +``` + +See [`Collection.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +in the _go-driver_ v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +String schemaRule = ( + "{" + + " \"type\": \"object\"," + + " \"properties\": {" + + " \"nums\": {" + + " \"type\": \"array\"," + + " \"items\": {" + + " \"type\": \"number\"," + + " \"minimum\": 6" + + " }" + + " }" + + " }," + + " \"additionalProperties\": { \"type\": \"string\" }," + + " \"required\": [\"nums\"]" + + "}"); + +CollectionPropertiesOptions props = new CollectionPropertiesOptions() + .schema(new CollectionSchema() + .setRule(schemaRule) + .setLevel(CollectionSchema.Level.MODERATE) + .setMessage("The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string.") + ); + +ArangoCollection coll = db.collection("coll"); +CollectionPropertiesEntity = coll.changeProperties(props); +``` + +See [`ArangoCollection.changeProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#changeProperties%28com.arangodb.model.CollectionPropertiesOptions%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") +props = coll.configure( + sync=True, + schema={ + "rule": { + "type": "object", + "properties": { + "nums": { + "type": "array", + "items": { + "type": "number", + "maximum": 6 + } + } + }, + "additionalProperties": { "type": "string" }, + "required": [ "nums" ] + }, + "level": "moderate", + "message": "The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string." + } +) ``` +See [`Collection.configure()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.configure) +in the _python-arango_ documentation for details. +{{< /tab >}} + +{{< /tabs >}} + ## JSON Schema Rule The `rule` must be a valid JSON Schema object as outlined in the diff --git a/site/content/3.12/concepts/data-structure/views.md b/site/content/3.12/concepts/data-structure/views.md index b22a27ad8..5c29464f3 100644 --- a/site/content/3.12/concepts/data-structure/views.md +++ b/site/content/3.12/concepts/data-structure/views.md @@ -154,16 +154,15 @@ description: | Create a View with default properties: --- ~db._createView("myView", "search-alias"); -var viewSearch = db._createView("myArangoSearchView", "arangosearch"); -var viewAlias = db._createView("mySearchAliasView", "search-alias"); +viewSearch = db._createView("myArangoSearchView", "arangosearch"); +viewAlias = db._createView("mySearchAliasView", "search-alias"); ~addIgnoreView("myView"); ~addIgnoreView("myArangoSearchView"); ~addIgnoreView("mySearchAliasView"); ``` -See `db._createView()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_createviewname-type--properties) -for details. +See [`db._createView()`](../../develop/javascript-api/@arangodb/db-object.md#db_createviewname-type--properties) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -172,7 +171,7 @@ curl -d '{"name":"myView1","type":"arangosearch"}' http://localhost:8529/_db/myd curl -d '{"name":"myView2","type":"search-alias"}' http://localhost:8529/_db/mydb/_api/view ``` -See `POST /_db/{database-name}/_api/view` in the HTTP API for details: +See the `POST /_db/{database-name}/_api/view` endpoint in the _HTTP API_ for details: - [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#create-an-arangosearch-view) - [`search-alias` View](../../develop/http-api/views/search-alias-views.md#create-a-search-alias-view) {{< /tab >}} @@ -183,9 +182,8 @@ let viewSearch = db.createView("myArangoSearchView", { type: "arangosearch" }); let viewAlias = db.createView("mySearchAliasView", { type: "search-alias" }); ``` -See `Database.createView()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createView) -for details. +See [`Database.createView()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#createView) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -196,7 +194,7 @@ viewAlias, err := db.CreateArangoSearchAliasView(ctx, "myArangoSearchView", nil) ``` See `DatabaseView.CreateArangoSearchView()` and `DatabaseView.CreateArangoSearchAliasView()` -in the [go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseView) +in the [_go-driver_ v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseView) for details. {{< /tab >}} @@ -211,7 +209,7 @@ ViewEntity viewAlias = db.createSearchAlias("mySearchAliasView", null); See `ArangoDatabase.createView()`, `ArangoDatabase.createArangoSearch()`, and `ArangoDatabase.createSearchAlias()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html) +[_arangodb-java-driver_ documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html) for details. {{< /tab >}} @@ -220,9 +218,8 @@ for details. info = db.create_view("myView", "arangosearch") ``` -See `StandardDatabase.create_view()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_view) -for details. +See [`StandardDatabase.create_view()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.create_view) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -245,12 +242,11 @@ name: viewUsage_02 description: | Get the View called `myView` by its name: --- -var view = db._view("myView"); +view = db._view("myView"); ``` -See `db._view()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/db-object.md#db_viewview) -for details. +See [`db._view()`](../../develop/javascript-api/@arangodb/db-object.md#db_viewview) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -258,8 +254,8 @@ for details. curl http://localhost:8529/_db/mydb/_api/view/myView ``` -See `GET /_db/{database-name}/_api/view/{view-name}` in the -[HTTP API](../../develop/http-api/views/_index.md) for details. +See the [`GET /_db/{database-name}/_api/view/{view-name}`](../../develop/http-api/views/_index.md) +endpoint in the _HTTP API_ for details. {{< /tab >}} {{< tab "JavaScript" >}} @@ -268,8 +264,8 @@ let view = db.view("myView"); const info = await view.get(); ``` -See `Database.view()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#view) +See [`Database.view()`](https://arangodb.github.io/arangojs/latest/classes/database.Database.html#view) +in the _arangojs_ documentation for details. {{< /tab >}} @@ -279,9 +275,8 @@ ctx := context.Background() view, err := db.View(ctx, "myView") ``` -See `DatabaseView.View()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseView) -for details. +See [`DatabaseView.View()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseView) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -294,7 +289,7 @@ SearchAlias viewAlias = db.searchAlias("mySearchAliasView"); See `ArangoDatabase.view(String name)`, `ArangoDatabase.arangoSearch(String name)`, and `ArangoDatabase.searchAlias(String name)` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html) +[_arangodb-java-driver_ documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html) for details. {{< /tab >}} @@ -303,9 +298,8 @@ for details. info = db.view_info("myView") ``` -See `StandardDatabase.view()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.view) -for details. +See [`StandardDatabase.view()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.view) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -331,9 +325,8 @@ var view = db._view("myView"); view.properties(); ``` -See `view.properties()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/view-object.md#viewpropertiesnew-properties--partialupdate) -for details. +See [`view.properties()`](../../develop/javascript-api/@arangodb/view-object.md#viewpropertiesnew-properties--partialupdate) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -341,7 +334,8 @@ for details. curl http://localhost:8529/_db/mydb/_api/view/myView/properties ``` -See `GET /_db/{database-name}/_api/view/{view-name}/properties` in the HTTP API for details: +See the `GET /_db/{database-name}/_api/view/{view-name}/properties` endpoint in +the _HTTP API_ for details: - [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#get-the-properties-of-a-view) - [`search-alias` View](../../develop/http-api/views/search-alias-views.md#get-information-about-a-view) {{< /tab >}} @@ -352,9 +346,8 @@ let view = db.view("myView"); const props = await view.properties(); ``` -See `View.properties()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/view.View.html#properties) -for details. +See [`View.properties()`](https://arangodb.github.io/arangojs/latest/classes/view.View.html#properties) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -380,7 +373,7 @@ default: See [`ArangoSearchView.Properties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchView) and [`ArangoSearchViewAlias.Properties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchViewAlias) -in the go-driver v2 documentation for details. +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -392,10 +385,9 @@ SearchAlias viewAlias = db.view("mySearchAliasView"); SearchAliasPropertiesEntity viewAlias.getProperties(); ``` -See `ArangoSearch.getProperties()` and `SearchAlias.getProperties()` -in the arangodb-java-driver documentation for details: -- [`arangosearch` View](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoSearch.html#getProperties%28%29) -- [`search-alias` View](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/SearchAlias.html#getProperties%28%29) +See [`ArangoSearch.getProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoSearch.html#getProperties%28%29) +and [`SearchAlias.getProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/SearchAlias.html#getProperties%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -403,14 +395,13 @@ in the arangodb-java-driver documentation for details: props = db.view("myView") ``` -See `StandardDatabase.view()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.view) -for details. +See [`StandardDatabase.view()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.view) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} -### Set a View property +### Set View properties {{< tabs "interfaces" >}} @@ -453,9 +444,8 @@ viewAlias.properties({ ~db._drop("coll"); ``` -See `view.properties()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/view-object.md#viewpropertiesnew-properties--partialupdate) -for details. +See [`view.properties()`](../../develop/javascript-api/@arangodb/view-object.md#viewpropertiesnew-properties--partialupdate) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -464,7 +454,8 @@ curl -XPATCH -d '{"cleanupIntervalStep":12,"links":{"coll":{"includeAllFields":t curl -XPATCH -d '{"indexes":[{"collection":"coll","index":"idx"}]}' http://localhost:8529/_db/mydb/_api/view/mySearchAliasView/properties ``` -See `PATCH /_db/{database-name}/_api/view/{view-name}/properties` in the HTTP API for details: +See the `PATCH /_db/{database-name}/_api/view/{view-name}/properties` endpoint +in the _HTTP API_ for details: - [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#update-the-properties-of-an-arangosearch-view) - [`search-alias` View](../../develop/http-api/views/search-alias-views.md#update-the-properties-of-a-search-alias-view) {{< /tab >}} @@ -482,9 +473,8 @@ const info = await view.updateProperties({ }); ``` -See `View.updateProperties()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/view.View.html#updateProperties) -for details. +See [`View.updateProperties()`](https://arangodb.github.io/arangojs/latest/classes/view.View.html#updateProperties) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -515,7 +505,7 @@ err := viewAlias.SetProperties(ArangoSearchAliasViewProperties{ See [`ArangoSearchView.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchView) and [`ArangoSearchViewAlias.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#ArangoSearchViewAlias) -in the go-driver v2 documentation for details. +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -538,7 +528,7 @@ SearchAliasPropertiesEntity viewAlias.updateProperties( See [`ArangoSearch.updateProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoSearch.html#updateProperties%28com.arangodb.model.arangosearch.ArangoSearchPropertiesOptions%29) and [`SearchAlias.updateProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/SearchAlias.html#updateProperties%28com.arangodb.model.arangosearch.SearchAliasPropertiesOptions%29) -in the arangodb-java-driver documentation for details. +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -559,9 +549,8 @@ props = db.update_view("mySearchAliasView", { }) ``` -See `StandardDatabase.update_view()` in the -[python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.update_view) -for details. +See [`StandardDatabase.update_view()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.update_view) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} @@ -575,7 +564,7 @@ for details. that contains the desired View. 2. Click **Views** in the main navigation. 3. Click the name or row of the desired View. -4. Click the **Delete** button and confirm. +4. Click the **Delete** button and confirm the deletion. {{< /tab >}} {{< tab "arangosh" >}} @@ -592,9 +581,8 @@ db._dropView("myView"); ~db._dropView("mySearchAliasView"); ``` -See `db._dropView()` in the -[JavaScript API](../../develop/javascript-api/@arangodb/view-object.md#viewdrop) -for details. +See [`db._dropView()`](../../develop/javascript-api/@arangodb/view-object.md#viewdrop) +in the _JavaScript API_ for details. {{< /tab >}} {{< tab "cURL" >}} @@ -602,7 +590,8 @@ for details. curl -XDELETE http://localhost:8529/_db/mydb/_api/view/myView ``` -See `DELETE /_db/{database-name/_api/view/{view-name}` in the HTTP API for details: +See the `DELETE /_db/{database-name/_api/view/{view-name}` endpoint in the +_HTTP API_ for details: - [`arangosearch` View](../../develop/http-api/views/arangosearch-views.md#drop-a-view) - [`search-alias` View](../../develop/http-api/views/search-alias-views.md#drop-a-view) {{< /tab >}} @@ -613,9 +602,8 @@ let view = db.view("myView"); const ok = view.drop(); ``` -See `View.drop()` in the -[arangojs documentation](https://arangodb.github.io/arangojs/latest/classes/view.View.html#drop) -for details. +See [`View.drop()`](https://arangodb.github.io/arangojs/latest/classes/view.View.html#drop) +in the _arangojs_ documentation for details. {{< /tab >}} {{< tab "Go" >}} @@ -625,9 +613,8 @@ view, err := db.View(ctx, "myView") err = view.Remove(ctx) ``` -See `View.Remove()` in the -[go-driver v2 documentation](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#View) -for details. +See [`View.Remove()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#View) +in the _go-driver_ v2 documentation for details. {{< /tab >}} {{< tab "Java" >}} @@ -636,9 +623,8 @@ ArangoView view = db.view("myView"); view.drop(); ``` -See `StandardDatabase.delete_view()` in the -[arangodb-java-driver documentation](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoView.html#drop%28%29) -for details. +See [`ArangoView.drop()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoView.html#drop%28%29) +in the _arangodb-java-driver_ documentation for details. {{< /tab >}} {{< tab "Python" >}} @@ -646,8 +632,8 @@ for details. ok = db.delete_view("myView") ``` -See the [python-arango documentation](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_view) -for details. +See [`StandardDatabase.delete_view()`](https://docs.python-arango.com/en/main/specs.html#arango.database.StandardDatabase.delete_view) +in the _python-arango_ documentation for details. {{< /tab >}} {{< /tabs >}} diff --git a/site/content/3.12/index-and-search/arangosearch/_index.md b/site/content/3.12/index-and-search/arangosearch/_index.md index b414a0372..4ac2bea33 100644 --- a/site/content/3.12/index-and-search/arangosearch/_index.md +++ b/site/content/3.12/index-and-search/arangosearch/_index.md @@ -142,7 +142,7 @@ View building is in progress and results can be incomplete. 2. In the **Collections** section of the web interface, click the `food` collection. 3. Go to the **Indexes** tab and click **Add Index**. 4. Select **Inverted index** as the **Type**. - 5. In the **Fields** panel, enter `name` into **Fields** and confirm. + 5. In the **Fields** panel, enter `name` into **Fields** and confirm the value. Then also add `type[*]` as a field. The `[*]` is needed to index the individual elements of the `type` array. Note that all `type` attributes of the example documents are arrays, even if @@ -316,7 +316,7 @@ English text. In the **Collections** section of the web interface, go to the **Indexes** tab and click **Add Index**. 2. Select **Inverted index** as the **Type**. - 3. In the **Fields** panel, enter `name` into **Fields** and confirm. + 3. In the **Fields** panel, enter `name` into **Fields** and confirm the value. 4. Click the underlined `name` field and select `text_en` as **Analyzer**. Note that every field can only be indexed with a single Analyzer in inverted indexes and `search-alias` Views. @@ -366,7 +366,7 @@ English text. 1. In the **Views** section of the web interface, click the card of the previously created `food_view` of type `arangosearch`. 2. In the **Links** panel, click the underlined name of the - `food` collection. Enter `name` into **Fields** and confirm. + `food` collection. Enter `name` into **Fields** and confirm the value. 3. Click the underlined name of the field and select the **Analyzers** `text_en` and `identity`. From 863a3ff2c7100df99fa8650fe59e9d707d3c59b6 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 17 Dec 2024 21:55:56 +0100 Subject: [PATCH 5/9] Fix link --- .../3.12/concepts/data-structure/documents/schema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/3.12/concepts/data-structure/documents/schema-validation.md b/site/content/3.12/concepts/data-structure/documents/schema-validation.md index c34ab7ab9..438ff0996 100644 --- a/site/content/3.12/concepts/data-structure/documents/schema-validation.md +++ b/site/content/3.12/concepts/data-structure/documents/schema-validation.md @@ -29,7 +29,7 @@ object with the following attributes: `rule`, `level` and `message`. {{< tabs "interfaces" >}} {{< tab "Web interface" >}} -1. If necessary, [switch to the database](databases.md#set-the-database-context) +1. If necessary, [switch to the database](../databases.md#set-the-database-context) that contains the desired collection. 2. Click **Collections** in the main navigation. 3. Click the name or row of the desired collection. From 52c9e86b540f8f21d5062634bf184877fcc907ee Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 17 Dec 2024 22:02:34 +0100 Subject: [PATCH 6/9] Fix another link --- .../3.12/concepts/data-structure/documents/schema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/3.12/concepts/data-structure/documents/schema-validation.md b/site/content/3.12/concepts/data-structure/documents/schema-validation.md index 438ff0996..c6a86e5d6 100644 --- a/site/content/3.12/concepts/data-structure/documents/schema-validation.md +++ b/site/content/3.12/concepts/data-structure/documents/schema-validation.md @@ -112,7 +112,7 @@ in the _JavaScript API_ for details. curl -XPUT -d '{"schema":{"rule":{"type":"object","properties":{"nums":{"type":"array","items":{"type":"number","minimum":6}}},"additionalProperties":{"type":"string"},"required":["nums"]},"level":"moderate","message":"The document does not contain an array of numbers in attribute \"nums\", one of the numbers is greater than 6, or another top-level attribute is not a string."}}' http://localhost:8529/_db/mydb/_api/collection/coll/properties ``` -See the [`GET /_db/{database-name}/_api/collection/{collection-name}/properties`](../../develop/http-api/collections.md#get-the-properties-of-a-collection) +See the [`GET /_db/{database-name}/_api/collection/{collection-name}/properties`](../../../develop/http-api/collections.md#get-the-properties-of-a-collection) endpoint in the _HTTP API_for details. {{< /tab >}} From 05c8e5559655430a68b051e73bab98a03d09e8e7 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Jan 2025 22:17:40 +0100 Subject: [PATCH 7/9] README: cURL example can fail if the URL doesn't specify /_db/_system for endpoints that require this context --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index b20db2787..86731d570 100644 --- a/README.md +++ b/README.md @@ -1384,6 +1384,11 @@ logJsonResponse(response); ``` ```` +If an endpoint requires the `_system` database as the context, the URL should be +set accordingly, e.g. `var url = "/_db/_system/_api/database";`. This ensures +that the request is issued correctly as the toolchain may process other examples +that change the database context simultaneously. + Unlike arangosh examples (`` ```js ``), requests and responses need to be output explicitly by calling one of the following functions: From da0cdf866fbf948fe454e22fe6704197bf27b50b Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Jan 2025 22:38:18 +0100 Subject: [PATCH 8/9] Fix arangosh example ID --- .../3.12/concepts/data-structure/documents/schema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/3.12/concepts/data-structure/documents/schema-validation.md b/site/content/3.12/concepts/data-structure/documents/schema-validation.md index c6a86e5d6..23bb44494 100644 --- a/site/content/3.12/concepts/data-structure/documents/schema-validation.md +++ b/site/content/3.12/concepts/data-structure/documents/schema-validation.md @@ -61,7 +61,7 @@ object with the following attributes: `rule`, `level` and `message`. {{< tab "arangosh" >}} ```js --- -name: arangosh_set_collection_properties +name: arangosh_set_collection_properties_schema description: '' --- var schema = { From 34923f14d6f32865675a24af12d8956c17659e80 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 20 Jan 2025 22:40:14 +0100 Subject: [PATCH 9/9] Computed values interface examples --- .../documents/computed-values.md | 181 +++++++++++++++++- .../version-3.10/api-changes-in-3-10.md | 2 +- 2 files changed, 172 insertions(+), 11 deletions(-) diff --git a/site/content/3.12/concepts/data-structure/documents/computed-values.md b/site/content/3.12/concepts/data-structure/documents/computed-values.md index 0c522ac26..5eec676bf 100644 --- a/site/content/3.12/concepts/data-structure/documents/computed-values.md +++ b/site/content/3.12/concepts/data-structure/documents/computed-values.md @@ -37,14 +37,10 @@ Computed value definitions are included in dumps, and the attributes they added, too, but no expressions are executed when restoring dumps. The collections and documents are restored as they are in the dump and no attributes are recalculated. -## JavaScript API +## Interfaces The `computedValues` collection property accepts an array of objects. -`db._create(, { computedValues: [ { … }, … ] })` - -`db..properties({ computedValues: [ { … }, … ] })` - Each object represents a computed value and can have the following attributes: - `name` (string, _required_): @@ -74,12 +70,174 @@ Each object represents a computed value and can have the following attributes: Whether to let the write operation fail if the expression produces a warning. The default is `false`. -## HTTP API +The names and data types differ in some of the drivers. + +{{< tabs "interfaces" >}} + +{{< tab "Web interface" >}} +1. If necessary, [switch to the database](../databases.md#set-the-database-context) + that contains the desired collection. +2. Click **Collections** in the main navigation. +3. Click the name or row of the desired collection. +4. Go to the **Computed Values** tab. +5. Edit the configuration in JSON format. Example: + ```json + [ + { + "name": "title", + "expression": "RETURN \"TBA\"", + "overwrite": false, + "computeOn": ["insert", "update", "replace"], + "failOnWarning": false, + "keepNull": true + } + ] + ``` +6. Click the **Save** button. +{{< /tab >}} + +{{< tab "arangosh" >}} +```js +--- +name: arangosh_set_collection_computed_values +description: '' +--- +var computedValues = [ + { + name: "title", + expression: "RETURN \"TBA\"", + overwrite: false, + computeOn: ["insert", "update", "replace"], + failOnWarning: false, + keepNull: true + } +]; + +/* Create a new collection with computed values */ +var coll = db._create("compValCollection", { computedValues }); + +/* Update the computed values of an existing collection */ +db.compValCollection.properties({ computedValues }); +~addIgnoreCollection(coll.name()); +``` +To remove the computed values configuration from a collection, set the +`computedValues` property to `null` or `[]` (empty array): + +```js +--- +name: arangosh_unset_collection_properties_computed_values +description: '' +--- +~var coll = db._collection("compValCollection"); +/* Remove the computed values of an existing collection */ +db.compValCollection.properties({ computedValues: null }); +~removeIgnoreCollection(coll.name()); +~db._drop(coll.name()); +``` + +See [`db._create()`](../../../develop/javascript-api/@arangodb/db-object.md#db_createcollection-name--properties--type--options) +and [`collection.properties()`](../../../develop/javascript-api/@arangodb/collection-object.md#collectionpropertiesproperties) +in the _JavaScript API_ for details. +{{< /tab >}} + +{{< tab "cURL" >}} +```sh +curl -XPUT -d '{"computedValues":[{"name":"title","expression":"RETURN \"TBA\"","overwrite":false,"computeOn":["insert","update","replace"],"failOnWarning":false,"keepNull":true}]' http://localhost:8529/_db/mydb/_api/collection/coll/properties +``` + +See the [`PUT /_db/{database-name}/_api/collection/{collection-name}/properties`](../../../develop/http-api/collections.md#change-the-properties-of-a-collection) +endpoint in the _HTTP API_for details. +{{< /tab >}} + +{{< tab "JavaScript" >}} +```js +let coll = db.collection("coll"); +const props = await coll.properties({ + computedValues: [ + { + name: "title", + expression: "RETURN \"TBA\"", + overwrite: false, + computeOn: ["insert", "update", "replace"], + failOnWarning: false, + keepNull: true + } + ] +}); +``` + +See [`DocumentCollection.properties()`](https://arangodb.github.io/arangojs/latest/interfaces/collection.DocumentCollection.html#properties.properties-2) +in the _arangojs_ documentation for details. +{{< /tab >}} + +{{< tab "Go" >}} +```go +ctx := context.Background() +coll, err := db.GetCollection(ctx, "coll", nil) +err = coll.SetProperties(ctx, arangodb.SetCollectionPropertiesOptions{ + ComputedValues: []arangodb.ComputedValue { + { + Name: "title", + Expression: "RETURN \"TBA\"", + Overwrite: false, + ComputeOn: []arangodb.ComputeOn { + arangodb.ComputeOnInsert, + arangodb.ComputeOnUpdate, + arangodb.ComputeOnReplace, + }, + FailOnWarning: utils.NewType(false), // pointer to bool + KeepNull: utils.NewType(true), // pointer to bool + }, + }, +}) +``` + +See [`Collection.SetProperties()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#Collection) +in the _go-driver_ v2 documentation for details. +{{< /tab >}} + +{{< tab "Java" >}} +```java +CollectionPropertiesOptions props = new CollectionPropertiesOptions() + .computedValues(new ComputedValue() + .name("title") + .expression("RETURN \"TBA\"") + .overwrite(false) + .computeOn(ComputeOn.insert, ComputeOn.update, ComputeOn.replace) + .failOnWarning(false) + .keepNull(true) + ); + +ArangoCollection coll = db.collection("coll"); +CollectionPropertiesEntity = coll.changeProperties(props); +``` + +See [`ArangoCollection.changeProperties()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoCollection.html#changeProperties%28com.arangodb.model.CollectionPropertiesOptions%29) +in the _arangodb-java-driver_ documentation for details. +{{< /tab >}} + +{{< tab "Python" >}} +```py +coll = db.collection("coll") +props = coll.configure( + computed_values: [ + { + "name": "title", + "expression": "RETURN \"TBA\"", + "overwrite": False, + "computeOn": ["insert", "update", "replace"], + "failOnWarning": False, + "keepNull": True + } + ] +) +``` + +See [`Collection.configure()`](https://docs.python-arango.com/en/main/specs.html#arango.collection.Collection.configure) +in the _python-arango_ documentation for details. +{{< /tab >}} -See the `computedValues` collection property in the HTTP API documentation: -- [Create a collection](../../../develop/http-api/collections.md#create-a-collection), -- [Read properties of a collection](../../../develop/http-api/collections.md#get-the-properties-of-a-collection), -- [Change properties of a collection](../../../develop/http-api/collections.md#change-the-properties-of-a-collection). +{{< /tabs >}} ## Computed Value Expressions @@ -143,6 +301,9 @@ of a collection. ## Examples +The following examples show a few ways you can use computed values using +_arangosh_. + Add an attribute with the creation timestamp to new documents: ```js diff --git a/site/content/3.12/release-notes/version-3.10/api-changes-in-3-10.md b/site/content/3.12/release-notes/version-3.10/api-changes-in-3-10.md index 8ceebb62a..981c3a1e7 100644 --- a/site/content/3.12/release-notes/version-3.10/api-changes-in-3-10.md +++ b/site/content/3.12/release-notes/version-3.10/api-changes-in-3-10.md @@ -976,7 +976,7 @@ every optimizer rule that briefly explains what it does. ### Computed values The Computed Values feature extends the collection properties with a new -`computedValues` attribute. See [Computed Values](../../concepts/data-structure/documents/computed-values.md#javascript-api) +`computedValues` attribute. See [Computed Values](../../concepts/data-structure/documents/computed-values.md#interfaces) for details. ### Query spillover and Read from followers