From 0593c113b62a275c8d34360f92265feb59116fba Mon Sep 17 00:00:00 2001 From: Paula Date: Mon, 27 Oct 2025 16:44:46 +0100 Subject: [PATCH 1/9] rename data science adapters --- site/content/ecosystem/adapters/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/ecosystem/adapters/_index.md b/site/content/ecosystem/adapters/_index.md index 267bcebac3..26d456e16f 100644 --- a/site/content/ecosystem/adapters/_index.md +++ b/site/content/ecosystem/adapters/_index.md @@ -1,6 +1,6 @@ --- -title: ArangoDB integrations for data science -menuTitle: Integrations +title: ArangoDB Adapters for data science +menuTitle: Data Science Adapters weight: 50 description: >- ArangoDB offers multiple adapters that enable seamless integration with From 2afc4f79228188e88b3ca74ea209f324344ef5e7 Mon Sep 17 00:00:00 2001 From: Paula Date: Mon, 27 Oct 2025 17:22:11 +0100 Subject: [PATCH 2/9] Move 3.12 drivers and integrations under ecosystem, fix links --- site/content/amp/deployments/_index.md | 2 +- .../x-509-certificates.md | 2 +- .../3.10/aql/functions/document-object.md | 2 +- .../3.10/develop/javascript-api/_index.md | 2 +- .../how-to-interact-with-arangodb.md | 2 +- .../3.10/get-started/start-using-aql.md | 4 +- .../3.10/operations/administration/_index.md | 2 +- .../3.11/aql/functions/document-object.md | 2 +- .../3.11/components/tools/arango-datasets.md | 2 +- .../3.11/develop/javascript-api/_index.md | 2 +- .../how-to-interact-with-arangodb.md | 2 +- .../3.11/operations/administration/_index.md | 2 +- .../3.12/aql/functions/document-object.md | 2 +- .../3.12/aql/how-to-invoke-aql/_index.md | 4 +- .../3.12/components/tools/arango-datasets.md | 2 +- .../arangodb/3.12/develop/http-api/_index.md | 2 +- .../3.12/develop/javascript-api/_index.md | 2 +- .../how-to-interact-with-arangodb.md | 2 +- .../3.12/operations/administration/_index.md | 2 +- .../3.13/aql/functions/document-object.md | 2 +- .../3.13/aql/how-to-invoke-aql/_index.md | 4 +- .../3.13/components/tools/arango-datasets.md | 2 +- .../3.13/develop/javascript-api/_index.md | 2 +- .../how-to-interact-with-arangodb.md | 2 +- .../3.13/operations/administration/_index.md | 2 +- site/content/ecosystem/_index.md | 37 ++++++++++++++++++- .../develop => ecosystem}/drivers/_index.md | 6 ++- .../3.12/develop => ecosystem}/drivers/go.md | 2 + .../drivers/java/_index.md | 4 +- .../java/reference-version-6/_index.md | 0 .../java/reference-version-6/driver-setup.md | 0 .../java/reference-version-6/serialization.md | 0 .../java/reference-version-7/_index.md | 0 .../changes-in-version-7.md | 0 .../java/reference-version-7/driver-setup.md | 0 .../java/reference-version-7/serialization.md | 0 .../drivers/javascript.md | 5 ++- .../develop => ecosystem}/drivers/python.md | 4 +- .../integrations/_index.md | 4 +- .../arangodb-datasource-for-apache-spark.md | 3 +- .../arangodb-tinkerpop-provider.md | 2 + .../_index.md | 4 +- .../configuration.md | 0 .../integrations/spring-boot-arangodb.md | 8 ++-- .../spring-data-arangodb/_index.md | 2 + .../spring-data-arangodb/migration.md | 0 .../reference-version-3/_index.md | 0 .../reference-version-3/mapping/_index.md | 0 .../reference-version-3/mapping/auditing.md | 0 .../reference-version-3/mapping/converter.md | 0 .../reference-version-3/mapping/document.md | 0 .../reference-version-3/mapping/edge.md | 0 .../reference-version-3/mapping/events.md | 0 .../reference-version-3/mapping/indexes.md | 4 +- .../reference-version-3/mapping/reference.md | 0 .../reference-version-3/mapping/relations.md | 0 .../repositories/_index.md | 0 .../repositories/queries/_index.md | 0 .../repositories/queries/derived-queries.md | 0 .../repositories/queries/named-queries.md | 0 .../repositories/queries/query-methods.md | 4 +- .../reference-version-3/template.md | 0 .../reference-version-4/_index.md | 0 .../reference-version-4/mapping/_index.md | 0 .../reference-version-4/mapping/auditing.md | 0 .../mapping/computed-values.md | 2 +- .../reference-version-4/mapping/converter.md | 0 .../reference-version-4/mapping/document.md | 0 .../reference-version-4/mapping/edge.md | 0 .../reference-version-4/mapping/events.md | 0 .../reference-version-4/mapping/indexes.md | 4 +- .../reference-version-4/mapping/reference.md | 0 .../reference-version-4/mapping/relations.md | 0 .../repositories/_index.md | 0 .../repositories/queries/_index.md | 0 .../repositories/queries/derived-queries.md | 0 .../repositories/queries/named-queries.md | 0 .../repositories/queries/query-methods.md | 4 +- .../reference-version-4/template.md | 0 79 files changed, 104 insertions(+), 51 deletions(-) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/_index.md (93%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/go.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/_index.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-6/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-6/driver-setup.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-6/serialization.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-7/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-7/changes-in-version-7.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-7/driver-setup.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/java/reference-version-7/serialization.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/javascript.md (96%) rename site/content/{arangodb/3.12/develop => ecosystem}/drivers/python.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/_index.md (98%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/arangodb-datasource-for-apache-spark.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/arangodb-tinkerpop-provider.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/kafka-connect-arangodb-sink-connector/_index.md (98%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/kafka-connect-arangodb-sink-connector/configuration.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-boot-arangodb.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/_index.md (99%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/migration.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/auditing.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/converter.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/document.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/edge.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/events.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md (93%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/reference.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/mapping/relations.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/repositories/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/repositories/queries/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/repositories/queries/derived-queries.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/repositories/queries/named-queries.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md (97%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-3/template.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/auditing.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md (92%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/converter.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/document.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/edge.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/events.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md (93%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/reference.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/mapping/relations.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/repositories/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/repositories/queries/_index.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/repositories/queries/derived-queries.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/repositories/queries/named-queries.md (100%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md (97%) rename site/content/{arangodb/3.12/develop => ecosystem}/integrations/spring-data-arangodb/reference-version-4/template.md (100%) diff --git a/site/content/amp/deployments/_index.md b/site/content/amp/deployments/_index.md index d8e67ac5ec..b331ed8163 100644 --- a/site/content/amp/deployments/_index.md +++ b/site/content/amp/deployments/_index.md @@ -273,7 +273,7 @@ attached to your role. Read more about [roles and permissions](../security-and-a ## How to connect a driver to your deployment -[ArangoDB drivers](../../arangodb/3.12/develop/drivers/_index.md) allow you to use your AMP +[ArangoDB drivers](../../ecosystem/drivers/) allow you to use your AMP deployment as a database system for your applications. Drivers act as interfaces between different programming languages and ArangoDB, which enable you to connect to and manipulate ArangoDB deployments from within compiled programs diff --git a/site/content/amp/security-and-access-control/x-509-certificates.md b/site/content/amp/security-and-access-control/x-509-certificates.md index 21e1e8493b..f17cf87e97 100644 --- a/site/content/amp/security-and-access-control/x-509-certificates.md +++ b/site/content/amp/security-and-access-control/x-509-certificates.md @@ -152,7 +152,7 @@ unique ID that is part of your AMP deployment endpoint URL. ## How to connect to your application -[ArangoDB drivers](../../arangodb/3.12/develop/drivers/_index.md), also called connectors, allow you to +[ArangoDB drivers](../../ecosystem/drivers/_index.md), also called connectors, allow you to easily connect AMP deployments to your application. 1. Navigate to **Deployments** and click the **View** button to show the diff --git a/site/content/arangodb/3.10/aql/functions/document-object.md b/site/content/arangodb/3.10/aql/functions/document-object.md index 31106af638..592c60515e 100644 --- a/site/content/arangodb/3.10/aql/functions/document-object.md +++ b/site/content/arangodb/3.10/aql/functions/document-object.md @@ -423,7 +423,7 @@ Only [`HAS()`](#has) can differentiate between an attribute being absent and hav a stored `null` value. An empty object `{}` will match all documents. Be careful not to ask for all -documents accidentally. For example, the [arangojs](../../develop/drivers/nodejs.md) driver +documents accidentally. For example, the [arangojs](../../../../ecosystem/drivers/javascript.md) driver skips attributes with a value of `undefined`, turning `{attr: undefined}` into `{}`. {{< info >}} diff --git a/site/content/arangodb/3.10/develop/javascript-api/_index.md b/site/content/arangodb/3.10/develop/javascript-api/_index.md index ac10a520f7..4147fb90a5 100644 --- a/site/content/arangodb/3.10/develop/javascript-api/_index.md +++ b/site/content/arangodb/3.10/develop/javascript-api/_index.md @@ -26,7 +26,7 @@ It communicates with the server via the HTTP API. {{< tip >}} The JavaScript API cannot be used in browsers, Node.js, or other JavaScript -environments. You can use the [arangojs driver](../drivers/nodejs.md) instead. +environments. You can use the [arangojs driver](../../../../ecosystem/drivers/javascript.md) instead. Note that it has a different interface. {{< /tip >}} diff --git a/site/content/arangodb/3.10/get-started/how-to-interact-with-arangodb.md b/site/content/arangodb/3.10/get-started/how-to-interact-with-arangodb.md index 896de02759..5f4eb6363b 100644 --- a/site/content/arangodb/3.10/get-started/how-to-interact-with-arangodb.md +++ b/site/content/arangodb/3.10/get-started/how-to-interact-with-arangodb.md @@ -34,7 +34,7 @@ interact with the server. You can also use it for automating tasks. ### Drivers and Integrations When you start using ArangoDB in your project, you will likely use an official -or community-made [driver](../develop/drivers/_index.md) written in the same language as your project. +or community-made [driver](../../../ecosystem/drivers/_index.md) written in the same language as your project. Drivers implement a programming interface that should feel natural for that programming language, and do all the talking to the server. diff --git a/site/content/arangodb/3.10/get-started/start-using-aql.md b/site/content/arangodb/3.10/get-started/start-using-aql.md index 5e4ade2c4c..f52398393c 100644 --- a/site/content/arangodb/3.10/get-started/start-using-aql.md +++ b/site/content/arangodb/3.10/get-started/start-using-aql.md @@ -34,8 +34,8 @@ for examples including tagged template strings. If you want to run AQL queries from your application via the HTTP REST API, see the full API description at [HTTP interface for AQL queries](../develop/http-api/queries/aql-queries.md). -See the respective [driver](../develop/drivers/_index.md) or -[integration](../develop/integrations/_index.md) for its support of AQL queries. +See the respective [driver](../../../ecosystem/drivers/_index.md) or +[integration](../../../ecosystem/integrations/_index.md) for its support of AQL queries. ## Learn the query language diff --git a/site/content/arangodb/3.10/operations/administration/_index.md b/site/content/arangodb/3.10/operations/administration/_index.md index 34012917ca..2e1e96de6a 100644 --- a/site/content/arangodb/3.10/operations/administration/_index.md +++ b/site/content/arangodb/3.10/operations/administration/_index.md @@ -26,7 +26,7 @@ Deployments of ArangoDB servers can be managed with the following tools: - **RESTful API**: _arangod_ has an [HTTP interface](../../develop/http-api/_index.md) through which it can be fully managed. The official client tools including _arangosh_ and the Web interface talk to this bare metal interface. It is also relevant for - [driver](../../develop/drivers/_index.md) developers. + [driver](../../../../ecosystem/drivers/_index.md) developers. - [**ArangoDB Starter**](../../components/tools/arangodb-starter/_index.md): This deployment tool helps to start _arangod_ instances, like for a Cluster or an Active Failover setup. diff --git a/site/content/arangodb/3.11/aql/functions/document-object.md b/site/content/arangodb/3.11/aql/functions/document-object.md index 4394f6fc4c..25da1b284a 100644 --- a/site/content/arangodb/3.11/aql/functions/document-object.md +++ b/site/content/arangodb/3.11/aql/functions/document-object.md @@ -425,7 +425,7 @@ Only [`HAS()`](#has) can differentiate between an attribute being absent and hav a stored `null` value. An empty object `{}` will match all documents. Be careful not to ask for all -documents accidentally. For example, the [arangojs](../../develop/drivers/javascript.md) driver +documents accidentally. For example, the [arangojs](../../../../ecosystem/drivers/javascript.md) driver skips attributes with a value of `undefined`, turning `{attr: undefined}` into `{}`. {{< info >}} diff --git a/site/content/arangodb/3.11/components/tools/arango-datasets.md b/site/content/arangodb/3.11/components/tools/arango-datasets.md index a24903550f..b2624f1438 100644 --- a/site/content/arangodb/3.11/components/tools/arango-datasets.md +++ b/site/content/arangodb/3.11/components/tools/arango-datasets.md @@ -27,7 +27,7 @@ You can find the source code repository of the module on GitHub: Once you have installed the `arango-datasets` package, you can use it to download and import datasets into your deployment with `arango_datasets.Datasets`. -The `Datasets` constructor requires a valid [python-arango](../../develop/drivers/python.md) +The `Datasets` constructor requires a valid [python-arango](../../../../../ecosystem/drivers/python.md) database object as input. It defines the target deployment, database, and credentials to load a dataset. diff --git a/site/content/arangodb/3.11/develop/javascript-api/_index.md b/site/content/arangodb/3.11/develop/javascript-api/_index.md index fb7146ff1b..4147fb90a5 100644 --- a/site/content/arangodb/3.11/develop/javascript-api/_index.md +++ b/site/content/arangodb/3.11/develop/javascript-api/_index.md @@ -26,7 +26,7 @@ It communicates with the server via the HTTP API. {{< tip >}} The JavaScript API cannot be used in browsers, Node.js, or other JavaScript -environments. You can use the [arangojs driver](../drivers/javascript.md) instead. +environments. You can use the [arangojs driver](../../../../ecosystem/drivers/javascript.md) instead. Note that it has a different interface. {{< /tip >}} diff --git a/site/content/arangodb/3.11/get-started/how-to-interact-with-arangodb.md b/site/content/arangodb/3.11/get-started/how-to-interact-with-arangodb.md index 896de02759..5f4eb6363b 100644 --- a/site/content/arangodb/3.11/get-started/how-to-interact-with-arangodb.md +++ b/site/content/arangodb/3.11/get-started/how-to-interact-with-arangodb.md @@ -34,7 +34,7 @@ interact with the server. You can also use it for automating tasks. ### Drivers and Integrations When you start using ArangoDB in your project, you will likely use an official -or community-made [driver](../develop/drivers/_index.md) written in the same language as your project. +or community-made [driver](../../../ecosystem/drivers/_index.md) written in the same language as your project. Drivers implement a programming interface that should feel natural for that programming language, and do all the talking to the server. diff --git a/site/content/arangodb/3.11/operations/administration/_index.md b/site/content/arangodb/3.11/operations/administration/_index.md index 34012917ca..2e1e96de6a 100644 --- a/site/content/arangodb/3.11/operations/administration/_index.md +++ b/site/content/arangodb/3.11/operations/administration/_index.md @@ -26,7 +26,7 @@ Deployments of ArangoDB servers can be managed with the following tools: - **RESTful API**: _arangod_ has an [HTTP interface](../../develop/http-api/_index.md) through which it can be fully managed. The official client tools including _arangosh_ and the Web interface talk to this bare metal interface. It is also relevant for - [driver](../../develop/drivers/_index.md) developers. + [driver](../../../../ecosystem/drivers/_index.md) developers. - [**ArangoDB Starter**](../../components/tools/arangodb-starter/_index.md): This deployment tool helps to start _arangod_ instances, like for a Cluster or an Active Failover setup. diff --git a/site/content/arangodb/3.12/aql/functions/document-object.md b/site/content/arangodb/3.12/aql/functions/document-object.md index a7272366aa..70496ccca7 100644 --- a/site/content/arangodb/3.12/aql/functions/document-object.md +++ b/site/content/arangodb/3.12/aql/functions/document-object.md @@ -477,7 +477,7 @@ Only [`HAS()`](#has) can differentiate between an attribute being absent and hav a stored `null` value. An empty object `{}` will match all documents. Be careful not to ask for all -documents accidentally. For example, the [arangojs](../../develop/drivers/javascript.md) driver +documents accidentally. For example, the [arangojs](../../../../ecosystem/drivers/javascript.md) driver skips attributes with a value of `undefined`, turning `{attr: undefined}` into `{}`. {{< info >}} diff --git a/site/content/arangodb/3.12/aql/how-to-invoke-aql/_index.md b/site/content/arangodb/3.12/aql/how-to-invoke-aql/_index.md index b44a6ed75a..1276ab8755 100644 --- a/site/content/arangodb/3.12/aql/how-to-invoke-aql/_index.md +++ b/site/content/arangodb/3.12/aql/how-to-invoke-aql/_index.md @@ -11,8 +11,8 @@ You can execute AQL queries using different interfaces: - The web interface - The `db` object of the JavaScript API (either in arangosh or in a Foxx service) - The raw HTTP REST API -- Through a [driver](../../develop/drivers/_index.md) or - [integration](../../develop/integrations/_index.md) as an abstraction over the +- Through a [driver](../../../../ecosystem/drivers/_index.md) or + [integration](../../../../ecosystem/integrations/_index.md) as an abstraction over the HTTP REST API There are always calls to the server's API under the hood, but the web interface, diff --git a/site/content/arangodb/3.12/components/tools/arango-datasets.md b/site/content/arangodb/3.12/components/tools/arango-datasets.md index a24903550f..b2624f1438 100644 --- a/site/content/arangodb/3.12/components/tools/arango-datasets.md +++ b/site/content/arangodb/3.12/components/tools/arango-datasets.md @@ -27,7 +27,7 @@ You can find the source code repository of the module on GitHub: Once you have installed the `arango-datasets` package, you can use it to download and import datasets into your deployment with `arango_datasets.Datasets`. -The `Datasets` constructor requires a valid [python-arango](../../develop/drivers/python.md) +The `Datasets` constructor requires a valid [python-arango](../../../../../ecosystem/drivers/python.md) database object as input. It defines the target deployment, database, and credentials to load a dataset. diff --git a/site/content/arangodb/3.12/develop/http-api/_index.md b/site/content/arangodb/3.12/develop/http-api/_index.md index e42c7b49f3..0357a030cb 100644 --- a/site/content/arangodb/3.12/develop/http-api/_index.md +++ b/site/content/arangodb/3.12/develop/http-api/_index.md @@ -13,7 +13,7 @@ world wide web. All interactions with a server are ultimately carried out via this HTTP API. You can use the API by sending HTTP requests to the server directly, but the -more common way of communicating with the server is via a [database driver](../drivers/_index.md). +more common way of communicating with the server is via a [database driver](../../../../ecosystem//drivers/_index.md). A driver abstracts the complexity of the API away by providing a simple interface for your programming language or environment and handling things like authentication, connection pooling, asynchronous requests, and multi-part replies diff --git a/site/content/arangodb/3.12/develop/javascript-api/_index.md b/site/content/arangodb/3.12/develop/javascript-api/_index.md index 1871086f86..349a0946b7 100644 --- a/site/content/arangodb/3.12/develop/javascript-api/_index.md +++ b/site/content/arangodb/3.12/develop/javascript-api/_index.md @@ -26,7 +26,7 @@ It communicates with the server via the HTTP API. {{< tip >}} The JavaScript API cannot be used in browsers, Node.js, or other JavaScript -environments. You can use the [arangojs driver](../drivers/javascript.md) instead. +environments. You can use the [arangojs driver](../../../../ecosystem/drivers/javascript.md) instead. Note that it has a different interface. {{< /tip >}} diff --git a/site/content/arangodb/3.12/get-started/how-to-interact-with-arangodb.md b/site/content/arangodb/3.12/get-started/how-to-interact-with-arangodb.md index ffceaf99dd..754709fc11 100644 --- a/site/content/arangodb/3.12/get-started/how-to-interact-with-arangodb.md +++ b/site/content/arangodb/3.12/get-started/how-to-interact-with-arangodb.md @@ -34,7 +34,7 @@ interact with the server. You can also use it for automating tasks. ### Drivers and Integrations When you start using ArangoDB in your project, you will likely use an official -or community-made [driver](../develop/drivers/_index.md) written in the same language as your project. +or community-made [driver](../../../ecosystem/drivers/_index.md) written in the same language as your project. Drivers implement a programming interface that should feel natural for that programming language, and do all the talking to the server. diff --git a/site/content/arangodb/3.12/operations/administration/_index.md b/site/content/arangodb/3.12/operations/administration/_index.md index ea48d0f8bb..74cb6fb8e3 100644 --- a/site/content/arangodb/3.12/operations/administration/_index.md +++ b/site/content/arangodb/3.12/operations/administration/_index.md @@ -26,7 +26,7 @@ Deployments of ArangoDB servers can be managed with the following tools: - **RESTful API**: _arangod_ has an [HTTP interface](../../develop/http-api/_index.md) through which it can be fully managed. The official client tools including _arangosh_ and the Web interface talk to this bare metal interface. It is also relevant for - [driver](../../develop/drivers/_index.md) developers. + [driver](../../../../ecosystem/drivers/_index.md) developers. - [**ArangoDB Starter**](../../components/tools/arangodb-starter/_index.md): This deployment tool helps to start _arangod_ instances, like for a Cluster setup. diff --git a/site/content/arangodb/3.13/aql/functions/document-object.md b/site/content/arangodb/3.13/aql/functions/document-object.md index a7272366aa..70496ccca7 100644 --- a/site/content/arangodb/3.13/aql/functions/document-object.md +++ b/site/content/arangodb/3.13/aql/functions/document-object.md @@ -477,7 +477,7 @@ Only [`HAS()`](#has) can differentiate between an attribute being absent and hav a stored `null` value. An empty object `{}` will match all documents. Be careful not to ask for all -documents accidentally. For example, the [arangojs](../../develop/drivers/javascript.md) driver +documents accidentally. For example, the [arangojs](../../../../ecosystem/drivers/javascript.md) driver skips attributes with a value of `undefined`, turning `{attr: undefined}` into `{}`. {{< info >}} diff --git a/site/content/arangodb/3.13/aql/how-to-invoke-aql/_index.md b/site/content/arangodb/3.13/aql/how-to-invoke-aql/_index.md index b44a6ed75a..1276ab8755 100644 --- a/site/content/arangodb/3.13/aql/how-to-invoke-aql/_index.md +++ b/site/content/arangodb/3.13/aql/how-to-invoke-aql/_index.md @@ -11,8 +11,8 @@ You can execute AQL queries using different interfaces: - The web interface - The `db` object of the JavaScript API (either in arangosh or in a Foxx service) - The raw HTTP REST API -- Through a [driver](../../develop/drivers/_index.md) or - [integration](../../develop/integrations/_index.md) as an abstraction over the +- Through a [driver](../../../../ecosystem/drivers/_index.md) or + [integration](../../../../ecosystem/integrations/_index.md) as an abstraction over the HTTP REST API There are always calls to the server's API under the hood, but the web interface, diff --git a/site/content/arangodb/3.13/components/tools/arango-datasets.md b/site/content/arangodb/3.13/components/tools/arango-datasets.md index a24903550f..b2624f1438 100644 --- a/site/content/arangodb/3.13/components/tools/arango-datasets.md +++ b/site/content/arangodb/3.13/components/tools/arango-datasets.md @@ -27,7 +27,7 @@ You can find the source code repository of the module on GitHub: Once you have installed the `arango-datasets` package, you can use it to download and import datasets into your deployment with `arango_datasets.Datasets`. -The `Datasets` constructor requires a valid [python-arango](../../develop/drivers/python.md) +The `Datasets` constructor requires a valid [python-arango](../../../../../ecosystem/drivers/python.md) database object as input. It defines the target deployment, database, and credentials to load a dataset. diff --git a/site/content/arangodb/3.13/develop/javascript-api/_index.md b/site/content/arangodb/3.13/develop/javascript-api/_index.md index 1871086f86..349a0946b7 100644 --- a/site/content/arangodb/3.13/develop/javascript-api/_index.md +++ b/site/content/arangodb/3.13/develop/javascript-api/_index.md @@ -26,7 +26,7 @@ It communicates with the server via the HTTP API. {{< tip >}} The JavaScript API cannot be used in browsers, Node.js, or other JavaScript -environments. You can use the [arangojs driver](../drivers/javascript.md) instead. +environments. You can use the [arangojs driver](../../../../ecosystem/drivers/javascript.md) instead. Note that it has a different interface. {{< /tip >}} diff --git a/site/content/arangodb/3.13/get-started/how-to-interact-with-arangodb.md b/site/content/arangodb/3.13/get-started/how-to-interact-with-arangodb.md index ffceaf99dd..754709fc11 100644 --- a/site/content/arangodb/3.13/get-started/how-to-interact-with-arangodb.md +++ b/site/content/arangodb/3.13/get-started/how-to-interact-with-arangodb.md @@ -34,7 +34,7 @@ interact with the server. You can also use it for automating tasks. ### Drivers and Integrations When you start using ArangoDB in your project, you will likely use an official -or community-made [driver](../develop/drivers/_index.md) written in the same language as your project. +or community-made [driver](../../../ecosystem/drivers/_index.md) written in the same language as your project. Drivers implement a programming interface that should feel natural for that programming language, and do all the talking to the server. diff --git a/site/content/arangodb/3.13/operations/administration/_index.md b/site/content/arangodb/3.13/operations/administration/_index.md index ea48d0f8bb..74cb6fb8e3 100644 --- a/site/content/arangodb/3.13/operations/administration/_index.md +++ b/site/content/arangodb/3.13/operations/administration/_index.md @@ -26,7 +26,7 @@ Deployments of ArangoDB servers can be managed with the following tools: - **RESTful API**: _arangod_ has an [HTTP interface](../../develop/http-api/_index.md) through which it can be fully managed. The official client tools including _arangosh_ and the Web interface talk to this bare metal interface. It is also relevant for - [driver](../../develop/drivers/_index.md) developers. + [driver](../../../../ecosystem/drivers/_index.md) developers. - [**ArangoDB Starter**](../../components/tools/arangodb-starter/_index.md): This deployment tool helps to start _arangod_ instances, like for a Cluster setup. diff --git a/site/content/ecosystem/_index.md b/site/content/ecosystem/_index.md index 578a53e1c4..e0a55de545 100644 --- a/site/content/ecosystem/_index.md +++ b/site/content/ecosystem/_index.md @@ -1,6 +1,39 @@ --- -title: Recommended Resources +title: Ecosystem menuTitle: Ecosystem weight: 5 layout: default ---- \ No newline at end of file +--- +The ArangoDB ecosystem includes official drivers, integrations, and adapters that +help you connect ArangoDB to your applications and data science tools. + +## Drivers + +Official [drivers](drivers/_index.md) for various programming languages allow you to +connect to and interact with ArangoDB from your applications: + +- [Java](drivers/java/_index.md) +- [Go](drivers/go.md) +- [JavaScript](drivers/javascript.md) +- [Python](drivers/python.md) + +## Integrations + +[Integrations](integrations/_index.md) for popular frameworks and tools: + +- [Spring Data & Spring Boot](integrations/spring-data-arangodb/_index.md) +- [Apache Spark](integrations/arangodb-datasource-for-apache-spark.md) +- [Apache Kafka](integrations/kafka-connect-arangodb-sink-connector/_index.md) +- [TinkerPop Provider](integrations/arangodb-tinkerpop-provider.md) + +## Adapters + +[Integrations for data science tools](adapters/_index.md) enable seamless integration +with popular data science and graph processing libraries: + +- [NetworkX](adapters/arangodb-networkx-adapter.md) +- [cuGraph](adapters/arangodb-cugraph-adapter.md) +- [PyTorch Geometric (PyG)](adapters/arangodb-pyg-adapter.md) +- [Deep Graph Library (DGL)](adapters/arangodb-dgl-adapter.md) +- [Resource Description Framework (RDF)](adapters/arangodb-rdf-adapter.md) +- [LangChain](adapters/langchain.md) \ No newline at end of file diff --git a/site/content/arangodb/3.12/develop/drivers/_index.md b/site/content/ecosystem/drivers/_index.md similarity index 93% rename from site/content/arangodb/3.12/develop/drivers/_index.md rename to site/content/ecosystem/drivers/_index.md index 6fc7ee3507..6587117c7d 100644 --- a/site/content/arangodb/3.12/develop/drivers/_index.md +++ b/site/content/ecosystem/drivers/_index.md @@ -1,10 +1,12 @@ --- title: Official ArangoDB drivers menuTitle: Drivers -weight: 285 +weight: 10 description: >- ArangoDB drivers allow you to connect ArangoDB to your applications and manage the database system via a language-specific interface +aliases: + - /3.12/develop/drivers/ --- Database drivers, also called connectors, adapters, or client libraries, let you access and manage database systems. ArangoDB drivers are interfaces between @@ -50,4 +52,4 @@ The [**Python-Arango**](python.md) driver lets you work with ArangoDB in the Python scripting language. - Online course: [Python Driver Tutorial](https://www.arangodb.com/tutorials/tutorial-python/) -- Repository: [github.com/ArangoDB-Community/python-arango](https://github.com/ArangoDB-Community/python-arango) +- Repository: [github.com/arangodb/python-arango](https://github.com/arangodb/python-arango) diff --git a/site/content/arangodb/3.12/develop/drivers/go.md b/site/content/ecosystem/drivers/go.md similarity index 99% rename from site/content/arangodb/3.12/develop/drivers/go.md rename to site/content/ecosystem/drivers/go.md index be7559eca1..926aa31baa 100644 --- a/site/content/arangodb/3.12/develop/drivers/go.md +++ b/site/content/ecosystem/drivers/go.md @@ -3,6 +3,8 @@ title: ArangoDB Go driver menuTitle: Go driver weight: 15 description: '' +aliases: + - /3.12/develop/drivers/go --- The official Go driver in version 2 is the recommended client for interacting with ArangoDB using the Go programming language. diff --git a/site/content/arangodb/3.12/develop/drivers/java/_index.md b/site/content/ecosystem/drivers/java/_index.md similarity index 99% rename from site/content/arangodb/3.12/develop/drivers/java/_index.md rename to site/content/ecosystem/drivers/java/_index.md index dc7d37d9fd..944ad1f5a2 100644 --- a/site/content/arangodb/3.12/develop/drivers/java/_index.md +++ b/site/content/ecosystem/drivers/java/_index.md @@ -3,6 +3,8 @@ title: ArangoDB Java driver menuTitle: Java driver weight: 10 description: '' +aliases: + - /3.12/develop/drivers/java/ --- The official ArangoDB Java Driver. @@ -341,7 +343,7 @@ Removed document: 6 ### Learn more -- Have a look at the [AQL documentation](../../../aql/) to lear about the +- Have a look at the [AQL documentation](../../../arangodb/3.12/aql/_index.md) to lear about the query language - See [Serialization](reference-version-7/serialization.md) for details about user-data serde diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-6/_index.md b/site/content/ecosystem/drivers/java/reference-version-6/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-6/_index.md rename to site/content/ecosystem/drivers/java/reference-version-6/_index.md diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-6/driver-setup.md b/site/content/ecosystem/drivers/java/reference-version-6/driver-setup.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-6/driver-setup.md rename to site/content/ecosystem/drivers/java/reference-version-6/driver-setup.md diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-6/serialization.md b/site/content/ecosystem/drivers/java/reference-version-6/serialization.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-6/serialization.md rename to site/content/ecosystem/drivers/java/reference-version-6/serialization.md diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-7/_index.md b/site/content/ecosystem/drivers/java/reference-version-7/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-7/_index.md rename to site/content/ecosystem/drivers/java/reference-version-7/_index.md diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-7/changes-in-version-7.md b/site/content/ecosystem/drivers/java/reference-version-7/changes-in-version-7.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-7/changes-in-version-7.md rename to site/content/ecosystem/drivers/java/reference-version-7/changes-in-version-7.md diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-7/driver-setup.md b/site/content/ecosystem/drivers/java/reference-version-7/driver-setup.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-7/driver-setup.md rename to site/content/ecosystem/drivers/java/reference-version-7/driver-setup.md diff --git a/site/content/arangodb/3.12/develop/drivers/java/reference-version-7/serialization.md b/site/content/ecosystem/drivers/java/reference-version-7/serialization.md similarity index 100% rename from site/content/arangodb/3.12/develop/drivers/java/reference-version-7/serialization.md rename to site/content/ecosystem/drivers/java/reference-version-7/serialization.md diff --git a/site/content/arangodb/3.12/develop/drivers/javascript.md b/site/content/ecosystem/drivers/javascript.md similarity index 96% rename from site/content/arangodb/3.12/develop/drivers/javascript.md rename to site/content/ecosystem/drivers/javascript.md index 5161b596b2..38b5ce6588 100644 --- a/site/content/arangodb/3.12/develop/drivers/javascript.md +++ b/site/content/ecosystem/drivers/javascript.md @@ -7,6 +7,7 @@ description: >- database system, primarily with Node.js aliases: - nodejs # 3.12 -> 3.12 + - /3.12/develop/drivers/javascript --- The official ArangoDB low-level JavaScript client. @@ -18,7 +19,7 @@ The official ArangoDB low-level JavaScript client. If you are looking for the ArangoDB JavaScript API in [Foxx](https://www.arangodb.com/community-server/foxx/) or the `arangosh` interactive shell, please refer to the documentation about the -[`@arangodb` module](../javascript-api/@arangodb/_index.md) instead. +[`@arangodb` module](../../arangodb/3.12/develop/javascript-api/@arangodb/_index.md) instead. The JavaScript driver is **only** meant to be used when accessing ArangoDB from **outside** the database. @@ -197,7 +198,7 @@ injection attacks. If the server returns an ArangoDB error response, arangojs throws an `ArangoError` with an `errorNum` property indicating the -[ArangoDB error code](../error-codes.md) and expose the response body +[ArangoDB error code](../../arangodb/3.12/develop/error-codes.md) and expose the response body as the response property of the error object. For all other errors during the request/response cycle arangojs throws a diff --git a/site/content/arangodb/3.12/develop/drivers/python.md b/site/content/ecosystem/drivers/python.md similarity index 99% rename from site/content/arangodb/3.12/develop/drivers/python.md rename to site/content/ecosystem/drivers/python.md index 4b028a616c..0f016bc2db 100644 --- a/site/content/arangodb/3.12/develop/drivers/python.md +++ b/site/content/ecosystem/drivers/python.md @@ -5,6 +5,8 @@ weight: 30 description: >- Python-Arango is the official ArangoDB driver that provides Python applications with the complete range of features exposed by the server API +aliases: + - /3.12/develop/drivers/python --- The Python-Arango driver is the recommended driver for using ArangoDB as the database backend from Python. It is maintained by ArangoDB and the community. @@ -169,7 +171,7 @@ await client.close() {{< /tabs >}} -The following example shows how to create a [named graph](../../graphs/_index.md), +The following example shows how to create a [named graph](../../arangodb/3.12/graphs/_index.md), populate it with nodes and edges, and query it with a graph traversal: {{< tabs "python-driver" >}} diff --git a/site/content/arangodb/3.12/develop/integrations/_index.md b/site/content/ecosystem/integrations/_index.md similarity index 98% rename from site/content/arangodb/3.12/develop/integrations/_index.md rename to site/content/ecosystem/integrations/_index.md index 3469808d73..7aee827ebf 100644 --- a/site/content/arangodb/3.12/develop/integrations/_index.md +++ b/site/content/ecosystem/integrations/_index.md @@ -1,10 +1,12 @@ --- title: Integrations menuTitle: Integrations -weight: 290 +weight: 20 description: >- Integrations for third-party tools and frameworks let you use ArangoDB as the database backend for these products +aliases: + - /3.12/develop/integrations/ --- Database integrations allow applications to work with different database systems using a common interface. They are higher-level than database drivers because diff --git a/site/content/arangodb/3.12/develop/integrations/arangodb-datasource-for-apache-spark.md b/site/content/ecosystem/integrations/arangodb-datasource-for-apache-spark.md similarity index 99% rename from site/content/arangodb/3.12/develop/integrations/arangodb-datasource-for-apache-spark.md rename to site/content/ecosystem/integrations/arangodb-datasource-for-apache-spark.md index aeaf9d379d..a5adab91ca 100644 --- a/site/content/arangodb/3.12/develop/integrations/arangodb-datasource-for-apache-spark.md +++ b/site/content/ecosystem/integrations/arangodb-datasource-for-apache-spark.md @@ -7,6 +7,7 @@ description: >- aliases: - arangodb-spark-connector - arangodb-spark-connector/getting-started +- /3.12/develop/integrations/arangodb-datasource-for-apache-spark - arangodb-spark-connector/reference - arangodb-spark-connector/reference/java - arangodb-spark-connector/reference/scala @@ -311,7 +312,7 @@ Use the `overwriteMode` write configuration parameter to specify the document ov ### Write Resiliency The data of each partition is saved in batches using the ArangoDB API for -[inserting multiple documents](../http-api/documents.md#multiple-document-operations). +[inserting multiple documents](../../../arangodb/3.12/develop/http-api/documents.md#multiple-document-operations). This operation is not atomic, therefore some documents could be successfully written to the database, while others could fail. To make the job more resilient to temporary errors (i.e. connectivity problems), in case of failure the request will be retried (with another Coordinator), if the provided configuration allows idempotent requests, namely: - the schema of the dataframe has a **not nullable** `_key` field and - `overwriteMode` is set to one of the following values: diff --git a/site/content/arangodb/3.12/develop/integrations/arangodb-tinkerpop-provider.md b/site/content/ecosystem/integrations/arangodb-tinkerpop-provider.md similarity index 99% rename from site/content/arangodb/3.12/develop/integrations/arangodb-tinkerpop-provider.md rename to site/content/ecosystem/integrations/arangodb-tinkerpop-provider.md index a1a68550bf..9ac59d0c42 100644 --- a/site/content/arangodb/3.12/develop/integrations/arangodb-tinkerpop-provider.md +++ b/site/content/ecosystem/integrations/arangodb-tinkerpop-provider.md @@ -4,6 +4,8 @@ menuTitle: TinkerPop Provider weight: 10 description: >- Build graph applications using TinkerPop API with ArangoDB's high-performance backend, combining Gremlin traversals and native AQL queries +aliases: + - /3.12/develop/integrations/arangodb-tinkerpop-provider --- ArangoDB TinkerPop Provider is an implementation of the [Apache TinkerPop OLTP Provider](https://tinkerpop.apache.org/docs/3.7.4/dev/provider) API for ArangoDB. diff --git a/site/content/arangodb/3.12/develop/integrations/kafka-connect-arangodb-sink-connector/_index.md b/site/content/ecosystem/integrations/kafka-connect-arangodb-sink-connector/_index.md similarity index 98% rename from site/content/arangodb/3.12/develop/integrations/kafka-connect-arangodb-sink-connector/_index.md rename to site/content/ecosystem/integrations/kafka-connect-arangodb-sink-connector/_index.md index 56fb0ba16f..dcea55aa00 100644 --- a/site/content/arangodb/3.12/develop/integrations/kafka-connect-arangodb-sink-connector/_index.md +++ b/site/content/ecosystem/integrations/kafka-connect-arangodb-sink-connector/_index.md @@ -5,6 +5,8 @@ weight: 20 description: >- The Kafka connector allows you to export data from Apache Kafka to ArangoDB by writing data from one or more topics in Kafka to a collection in ArangoDB +aliases: + - /3.12/develop/integrations/kafka-connect-arangodb-sink-connector/ --- {{< info >}} Check out the [connector demo](https://github.com/arangodb/kafka-connect-arangodb/tree/main/demo) @@ -206,7 +208,7 @@ behavior in case a document with the same `_key` already exists: All the write modes supported are idempotent, with the exception that the document revision field (`_rev`) changes every time a document is written. See -[Document revisions](../../../concepts/data-structure/documents/_index.md#document-revisions) +[Document revisions](../../../../arangodb/3.12/concepts/data-structure/documents/_index.md#document-revisions) for more details. If there are failures, the Kafka offset used for recovery may not be up-to-date diff --git a/site/content/arangodb/3.12/develop/integrations/kafka-connect-arangodb-sink-connector/configuration.md b/site/content/ecosystem/integrations/kafka-connect-arangodb-sink-connector/configuration.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/kafka-connect-arangodb-sink-connector/configuration.md rename to site/content/ecosystem/integrations/kafka-connect-arangodb-sink-connector/configuration.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-boot-arangodb.md b/site/content/ecosystem/integrations/spring-boot-arangodb.md similarity index 99% rename from site/content/arangodb/3.12/develop/integrations/spring-boot-arangodb.md rename to site/content/ecosystem/integrations/spring-boot-arangodb.md index 4633df80a8..aaae283545 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-boot-arangodb.md +++ b/site/content/ecosystem/integrations/spring-boot-arangodb.md @@ -5,6 +5,8 @@ weight: 7 description: >- The Spring Boot Starter for ArangoDB is a set of convenient dependency descriptors that you can include in your application based on the Spring framework +aliases: + - /3.12/develop/integrations/spring-boot-arangodb --- - [Repository](https://github.com/arangodb/spring-boot-starter) - [Demo](https://github.com/arangodb/spring-boot-starter/tree/main/demo) @@ -1056,10 +1058,10 @@ Character [id=2999, name=Cersei, surname=Lannister, alive=true, age=36] You can have repository methods with self-written AQL queries. When it comes to more complex use cases where a derived method would get way too -long and become unreadable, queries using the [ArangoDB Query Language (AQL)](../../aql/_index.md) +long and become unreadable, queries using the [ArangoDB Query Language (AQL)](../../../arangodb/3.12/aql/_index.md) can be supplied with the `@Query` annotation on methods in your repositories. -AQL supports the usage of [bind parameters](../../aql/fundamentals/bind-parameters.md), +AQL supports the usage of [bind parameters](../../../arangodb/3.12/aql/fundamentals/bind-parameters.md), thus allowing to separate the query text from literal values used in the query. There are three ways of passing bind parameters to the query in the `@Query` annotation that are described below. @@ -1229,7 +1231,7 @@ Character [id=9014, name=Cersei, surname=Lannister, alive=true, age=36] ### Graph traversal -To finish the query method topic, add a [graph traversal](../../aql/graphs/traversals.md) +To finish the query method topic, add a [graph traversal](../../../arangodb/3.12/aql/graphs/traversals.md) written in AQL to this demo where the `ChildOf` edges are involved. The following query searches for every `Character` connected (through `ChildOf`) diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/_index.md similarity index 99% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/_index.md index 568750e4ac..021c62f812 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/_index.md +++ b/site/content/ecosystem/integrations/spring-data-arangodb/_index.md @@ -5,6 +5,8 @@ weight: 5 description: >- The Spring Data ArangoDB integration is a library for accessing data stored in ArangoDB from Spring-based Java application +aliases: + - /3.12/develop/integrations/spring-data-arangodb/ --- Spring Data provides a consistent interface for accessing various types of data sources. Spring Data ArangoDB implements this diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/migration.md b/site/content/ecosystem/integrations/spring-data-arangodb/migration.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/migration.md rename to site/content/ecosystem/integrations/spring-data-arangodb/migration.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/auditing.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/auditing.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/auditing.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/auditing.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/converter.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/converter.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/converter.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/converter.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/document.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/document.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/document.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/document.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/edge.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/edge.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/edge.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/edge.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/events.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/events.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/events.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/events.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md similarity index 93% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md index 56cd6eb4e7..2e9c56af6d 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md +++ b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/indexes.md @@ -10,9 +10,9 @@ developed anymore. Upgrading to version 4 is recommended. {{< /warning >}} Indexes can be ensured using the following annotations. For reference see the -[indexing](../../../../../index-and-search/indexing/_index.md) documentation +[indexing](../../../../../../arangodb/3.12/index-and-search/indexing/_index.md) documentation and specific aspects that apply to -[indexes on shards](../../../../../deploy/architecture/data-sharding.md#indexes-on-shards). +[indexes on shards](../../../../../../arangodb/3.12/deploy/architecture/data-sharding.md#indexes-on-shards). ## Annotation @\Indexed diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/reference.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/reference.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/reference.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/reference.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/relations.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/relations.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/mapping/relations.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/mapping/relations.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/derived-queries.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/derived-queries.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/derived-queries.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/derived-queries.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/named-queries.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/named-queries.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/named-queries.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/named-queries.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md similarity index 97% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md index 231e9df1c8..61d85942ee 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md +++ b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/repositories/queries/query-methods.md @@ -9,7 +9,7 @@ Spring Data ArangoDB version 3 reached End of Life (EOL) and is not actively developed anymore. Upgrading to version 4 is recommended. {{< /warning >}} -Queries using [ArangoDB Query Language (AQL)](../../../../../../aql/_index.md) +Queries using [ArangoDB Query Language (AQL)](../../../../../../arangodb/3.12/aql/_index.md) can be supplied with the `@Query` annotation on methods. ## Passing collection name @@ -63,7 +63,7 @@ public interface MyRepository extends ArangoRepository{ In addition you can use a method parameter of type `Map` annotated with `@BindVars` as your bind parameters. You can then fill the map -with any parameter used in the query (also see [AQL Bind Parameters](../../../../../../aql/fundamentals/bind-parameters.md)). +with any parameter used in the query (also see [AQL Bind Parameters](../../../../../../arangodb/3.12/aql/fundamentals/bind-parameters.md)). ```java public interface MyRepository extends ArangoRepository{ diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/template.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/template.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-3/template.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-3/template.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/auditing.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/auditing.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/auditing.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/auditing.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md similarity index 92% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md index 59bf728d9a..298c70421c 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md +++ b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md @@ -9,7 +9,7 @@ Spring Data ArangoDB provides annotations to allow mapping computed values to entity properties and to include computed values data definitions during collection creation. -For reference, see the [computed values](../../../../../concepts/data-structure/documents/computed-values.md) +For reference, see the [computed values](../../../../../../arangodb/3.12/concepts/data-structure/documents/computed-values.md) documentation. ## Mapping diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/converter.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/converter.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/converter.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/converter.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/document.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/document.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/document.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/document.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/edge.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/edge.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/edge.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/edge.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/events.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/events.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/events.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/events.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md similarity index 93% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md index 7bd9a78c42..c226e0305b 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md +++ b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md @@ -5,9 +5,9 @@ weight: 25 description: '' --- Indexes can be ensured using the following annotations. For reference see the -[indexing](../../../../../index-and-search/indexing/_index.md) documentation +[indexing](../../../../../../arangodb/3.12/index-and-search/indexing/_index.md) documentation and specific aspects that apply to -[indexes on shards](../../../../../deploy/architecture/data-sharding.md#indexes-on-shards). +[indexes on shards](../../../../../../arangodb/3.12/deploy/architecture/data-sharding.md#indexes-on-shards). ## Annotation @\Indexed diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/reference.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/reference.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/reference.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/reference.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/relations.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/relations.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/mapping/relations.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/mapping/relations.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/_index.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/_index.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/_index.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/_index.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/derived-queries.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/derived-queries.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/derived-queries.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/derived-queries.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/named-queries.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/named-queries.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/named-queries.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/named-queries.md diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md similarity index 97% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md index 90f1fa74b9..13762b7e79 100644 --- a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md +++ b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md @@ -4,7 +4,7 @@ menuTitle: Query methods weight: 10 description: '' --- -Queries using [ArangoDB Query Language (AQL)](../../../../../../aql/_index.md) +Queries using [ArangoDB Query Language (AQL)](../../../../../../arangodb/3.12/aql/_index.md) can be supplied with the `@Query` annotation on methods. ## Passing collection name @@ -58,7 +58,7 @@ public interface MyRepository extends ArangoRepository{ In addition you can use a method parameter of type `Map` annotated with `@BindVars` as your bind parameters. You can then fill the map -with any parameter used in the query (also see [AQL Bind Parameters](../../../../../../aql/fundamentals/bind-parameters.md)). +with any parameter used in the query (also see [AQL Bind Parameters](../../../../../../arangodb/3.12/aql/fundamentals/bind-parameters.md)). ```java public interface MyRepository extends ArangoRepository{ diff --git a/site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/template.md b/site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/template.md similarity index 100% rename from site/content/arangodb/3.12/develop/integrations/spring-data-arangodb/reference-version-4/template.md rename to site/content/ecosystem/integrations/spring-data-arangodb/reference-version-4/template.md From cda3ab782a165a382efa6a012ca1a8829110264f Mon Sep 17 00:00:00 2001 From: Paula Date: Tue, 28 Oct 2025 14:29:53 +0100 Subject: [PATCH 3/9] remove drivers and integrations from 3.13, add aliases --- .../arangodb/3.13/develop/drivers/_index.md | 53 - .../arangodb/3.13/develop/drivers/go.md | 735 -------- .../3.13/develop/drivers/java/_index.md | 480 ------ .../java/reference-version-7/_index.md | 7 - .../changes-in-version-7.md | 448 ----- .../java/reference-version-7/driver-setup.md | 300 ---- .../java/reference-version-7/serialization.md | 247 --- .../3.13/develop/drivers/javascript.md | 224 --- .../arangodb/3.13/develop/drivers/python.md | 678 -------- .../arangodb/3.13/develop/http-api/_index.md | 2 +- .../3.13/develop/integrations/_index.md | 58 - .../arangodb-datasource-for-apache-spark.md | 422 ----- .../arangodb-tinkerpop-provider.md | 841 --------- .../_index.md | 283 ---- .../configuration.md | 244 --- .../integrations/spring-boot-arangodb.md | 1507 ----------------- .../spring-data-arangodb/_index.md | 237 --- .../spring-data-arangodb/migration.md | 109 -- .../reference-version-4/_index.md | 6 - .../reference-version-4/mapping/_index.md | 282 --- .../reference-version-4/mapping/auditing.md | 148 -- .../mapping/computed-values.md | 58 - .../reference-version-4/mapping/converter.md | 53 - .../reference-version-4/mapping/document.md | 97 -- .../reference-version-4/mapping/edge.md | 95 -- .../reference-version-4/mapping/events.md | 42 - .../reference-version-4/mapping/indexes.md | 123 -- .../reference-version-4/mapping/reference.md | 65 - .../reference-version-4/mapping/relations.md | 34 - .../repositories/_index.md | 47 - .../repositories/queries/_index.md | 125 -- .../repositories/queries/derived-queries.md | 218 --- .../repositories/queries/named-queries.md | 34 - .../repositories/queries/query-methods.md | 132 -- .../reference-version-4/template.md | 15 - site/content/ecosystem/drivers/_index.md | 1 + site/content/ecosystem/drivers/go.md | 1 + site/content/ecosystem/drivers/java/_index.md | 1 + site/content/ecosystem/drivers/javascript.md | 1 + site/content/ecosystem/drivers/python.md | 1 + site/content/ecosystem/integrations/_index.md | 1 + .../arangodb-datasource-for-apache-spark.md | 1 + .../arangodb-tinkerpop-provider.md | 1 + .../_index.md | 1 + .../integrations/spring-boot-arangodb.md | 1 + .../spring-data-arangodb/_index.md | 1 + 46 files changed, 12 insertions(+), 8448 deletions(-) delete mode 100644 site/content/arangodb/3.13/develop/drivers/_index.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/go.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/java/_index.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/java/reference-version-7/_index.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/java/reference-version-7/changes-in-version-7.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/java/reference-version-7/driver-setup.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/java/reference-version-7/serialization.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/javascript.md delete mode 100644 site/content/arangodb/3.13/develop/drivers/python.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/arangodb-datasource-for-apache-spark.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/arangodb-tinkerpop-provider.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/kafka-connect-arangodb-sink-connector/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/kafka-connect-arangodb-sink-connector/configuration.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-boot-arangodb.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/migration.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/auditing.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/computed-values.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/converter.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/document.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/edge.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/events.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/indexes.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/reference.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/mapping/relations.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/repositories/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/_index.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/derived-queries.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/named-queries.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/repositories/queries/query-methods.md delete mode 100644 site/content/arangodb/3.13/develop/integrations/spring-data-arangodb/reference-version-4/template.md diff --git a/site/content/arangodb/3.13/develop/drivers/_index.md b/site/content/arangodb/3.13/develop/drivers/_index.md deleted file mode 100644 index 6fc7ee3507..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/_index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Official ArangoDB drivers -menuTitle: Drivers -weight: 285 -description: >- - ArangoDB drivers allow you to connect ArangoDB to your applications and manage - the database system via a language-specific interface ---- -Database drivers, also called connectors, adapters, or client libraries, let you -access and manage database systems. ArangoDB drivers are interfaces between -programming languages and ArangoDB, which enable software developers to connect -to and manipulate ArangoDB deployments from within compiled programs or using -scripting languages. - -From a language perspective, documents and database structures can be integrated -with data types and their methods. The precise mapping of concepts and methods -depends on the capabilities and practices of each language. - -Programming is a powerful way of automating interactions and control of the -database, as well as to integrate database operations into your own software. -The drivers listed below are officially maintained and supported by ArangoDB. -If your programming language or environment is not listed, - -## Java driver - -The [**ArangoDB Java driver**](java/_index.md) lets you work with ArangoDB in the -Java programming language. - -- [Tutorial](java/_index.md#tutorial) -- Repository: [github.com/arangodb/arangodb-java-driver](https://github.com/arangodb/arangodb-java-driver) - -## Go driver - -The [**Go driver**](go.md) lets you work with ArangoDB in the Go programming -language. - -- [Tutorial](go.md#tutorial) -- Repository: [github.com/arangodb/go-driver](https://github.com/arangodb/go-driver/tree/master/v2) - -## JavaScript driver - -The [**ArangoJS driver**](javascript.md) lets you work with ArangoDB in Node.js, using -the JavaScript scripting language. You can also use it in web browsers. - -- Repository: [github.com/arangodb/arangojs](https://github.com/arangodb/arangojs) - -## Python driver - -The [**Python-Arango**](python.md) driver lets you work with ArangoDB in the -Python scripting language. - -- Online course: [Python Driver Tutorial](https://www.arangodb.com/tutorials/tutorial-python/) -- Repository: [github.com/ArangoDB-Community/python-arango](https://github.com/ArangoDB-Community/python-arango) diff --git a/site/content/arangodb/3.13/develop/drivers/go.md b/site/content/arangodb/3.13/develop/drivers/go.md deleted file mode 100644 index be7559eca1..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/go.md +++ /dev/null @@ -1,735 +0,0 @@ ---- -title: ArangoDB Go driver -menuTitle: Go driver -weight: 15 -description: '' ---- -The official Go driver in version 2 is the recommended client for interacting -with ArangoDB using the Go programming language. - -- Reference: -- Repository: -- [Changelog](https://github.com/arangodb/go-driver/blob/master/v2/CHANGELOG.md) - -## Tutorial - -### Install the driver - -To use the driver, fetch the sources into your `GOPATH` first. - -```sh -go get github.com/arangodb/go-driver/v2 -``` - -Import the driver in your Go program using the `import` statement. -Two packages are necessary: - -```go -import ( - "github.com/arangodb/go-driver/v2/arangodb" - "github.com/arangodb/go-driver/v2/connection" -) -``` - -You may want to additionally import the following packages: - -```go - "github.com/arangodb/go-driver/v2/arangodb/shared" - "github.com/arangodb/go-driver/v2/utils" -``` - -The former provides a `shared.IsNoMoreDocuments` function that makes it easy to -check whether to stop iterating over the results of functions that return a reader, -like multi-document operations and listing graphs. The latter provides a -`utils.NewType` function that lets you conveniently create a pointer to a boolean -value, for instance. - -If you use Go modules, you can also import the driver and run `go mod tidy` -instead of using the `go get` command. - -### Connect to ArangoDB - -Using the driver, you always need to create a `Client`. The following example -shows how to create a `Client` for an ArangoDB single server running on localhost. -You need to set `InsecureSkipVerify` to `true` if the ArangoDB server is not -configured for TLS encryption to establish an unencrypted HTTP/2 connection. -For more options, see [Connection management](#connection-management). - -```go -import ( - "context" - "log" - - "github.com/arangodb/go-driver/v2/arangodb" - "github.com/arangodb/go-driver/v2/arangodb/shared" - "github.com/arangodb/go-driver/v2/connection" - "github.com/arangodb/go-driver/v2/utils" -) - -/*...*/ - -endpoint := connection.NewRoundRobinEndpoints([]string{"http://localhost:8529"}) -conn := connection.NewHttp2Connection(connection.DefaultHTTP2ConfigurationWrapper(endpoint, /*InsecureSkipVerify*/ true)) - -// Add authentication -auth := connection.NewBasicAuth("root", "") -err := conn.SetAuthentication(auth) -if err != nil { - log.Fatalf("Failed to set authentication: %v", err) -} - -// Create a client -client := arangodb.NewClient(conn) -``` - -Once you have a `Client` object, you can use this handle to create and edit -objects, such as databases, collections, documents, and graphs. These database -objects are mapped to types in Go. The methods for these types are used to read -and write data. - -### Asynchronous client - -The driver supports an asynchronous client that can be used to run multiple -operations concurrently. - -```go -import ( - "context" - "log" - - "github.com/arangodb/go-driver/v2/arangodb" - "github.com/arangodb/go-driver/v2/connection" -) - -/*...*/ - -// Create an HTTP connection to the database -endpoint := connection.NewRoundRobinEndpoints([]string{"http://localhost:8529"}) -conn := connection.NewHttp2Connection(connection.DefaultHTTP2ConfigurationWrapper(endpoint, false)) - -auth := connection.NewBasicAuth("root", "password") -err := conn.SetAuthentication(auth) -if err != nil { - log.Fatalf("Failed to set authentication: %v", err) -} - -// Create ASYNC wrapper for the connection -conn = connection.NewConnectionAsyncWrapper(conn) - -// Create a client -client := arangodb.NewClient(conn) - -// Trigger async request -info, errWithJobID := client.Version(connection.WithAsync(context.Background())) -if errWithJobID == nil { - log.Fatalf("Error object should not be nil but be an async job id") -} -if info.Version != "" { - log.Printf("Expected empty version if async request is in progress, got %s", info.Version) -} - -// Fetch an async job id from the error -id, isAsyncId := connection.IsAsyncJobInProgress(errWithJobID) -if !isAsyncId { - log.Fatalf("Expected async job id, got %v", id) -} - -// Wait for an async result -time.Sleep(3 * time.Second) - -// List async jobs - there should be one, till the result is fetched -jobs, err := client.AsyncJobList(context.Background(), arangodb.JobDone, nil) -if err != nil { - log.Fatalf("Failed to list async jobs: %v", err) -} -if len(jobs) != 1 { - log.Fatalf("Expected 1 async job, got %d", len(jobs)) -} - -// Fetch an async job result -info, err = client.Version(connection.WithAsyncID(context.Background(), id)) -if err != nil { - log.Fatalf("Failed to fetch async job result: %v", err) -} -log.Printf("Async job result: %s", info.Version) -``` - -### Important types for Go - -Key types you need to know about to work with ArangoDB using the Go driver: - -- `Database` – to maintain a handle to an open database -- `Collection` – as a handle for a collection of records (node, edge, or document) within a database -- `Graph` – as a handle for a graph overlay containing nodes and edges -- `EdgeDefinition` – a named collection of edges used to help a graph in distributed searching - -These are declared as in the following examples: - -```go -var err error -var client arangodb.Client -var conn connection.Connection -var db arangodb.Database -var col arangodb.Collection -``` - -The following example shows how to open an existing collection in an existing -database and create a new document in that collection. - -```go -// Setup a client connection -endpoint := connection.NewRoundRobinEndpoints([]string{"https://abcdef123456.arangodb.cloud:8529/"}) -conn := connection.NewHttp2Connection(connection.DefaultHTTP2ConfigurationWrapper(endpoint, false)) - -// Add authentication -auth := connection.NewBasicAuth("root", "password") -err := conn.SetAuthentication(auth) -if err != nil { - log.Fatalf("Failed to set authentication: %v", err) -} - -// Create a client -client := arangodb.NewClient(conn) - -// Open the "mydb" database -db, err := client.GetDatabase(nil, "mydb", nil) -if err != nil { - // Handle error -} - -// Open the "coll" collection -col, err := db.GetCollection(nil, "coll", nil) -if err != nil { - // Handle error -} - -// Define a structure for (de)serializing documents -type Book struct { - Title string `json:"title"` - NoPages int `json:"number_pages,omitempty"` -} - -// Create a document -book := Book{ - Title: "ArangoDB Cookbook", - NoPages: 257, -} - -meta, err := col.CreateDocument(nil, book) -if err != nil { - // Handle error -} -log.Printf("Created document in collection '%s' in database '%s'\n", col.Name(), db.Name()) -``` - -### Relationships between Go types and JSON - -A basic principle of the integration between Go and ArangoDB is the mapping from -Go types to JSON documents. Data in the database map to types in Go through JSON. -You need at least two types in a Golang program to work with graphs. - -Go uses a special syntax to map values like struct members like Key, Weight, -Data, etc. to JSON fields. Remember that member names should start with a capital -letter to be accessible outside a packaged scope. You declare types and their -JSON mappings once, as in the examples below. - -```go -// A typical document type -type IntKeyValue struct { - Key string `json:"_key"` // mandatory field (handle) - short name - Value int `json:"value"` -} - -// A typical node type must have field matching _key -type MyNode struct { - Key string `json:"_key"` // mandatory field (handle) - short name - // other fields … e.g. - Data string `json: "data"` // Longer description or bulk string data - Weight float64 `json:"weight"` // importance rank -} - -// A typical edge type must have fields matching _from and _to -type MyEdge struct { - Key string `json:"_key"` // mandatory field (handle) - From string `json:"_from"` // mandatory field - To string `json:"_to"` // mandatory field - // other fields … e.g. - Weight float64 `json:"weight"` -} -``` - -When reading data from ArangoDB with, say, `ReadDocument()`, the API asks you to -submit a variable of some type, say `MyDocumentType`, by reference using the -`&` operator: - -```go -var variable MyDocumentType -mycollection.ReadDocument(nil, rawkey, &variable) -``` - -This submitted type is not necessarily a fixed type, but it must be a type whose -members map (at least partially) to the named fields in the database's JSON -document representation. Only matching fields are filled in. This means you could -create several different Go types to read the same documents in the database, as -long as they have some type fields that match JSON fields. In other words, the -mapping need not be unique or one-to-one, so there is great flexibility in making -new types to extract a subset of the fields in a document. - -The document model in ArangoDB does not require all documents in a collection to -have the same fields. You can choose to have ad hoc schemas and extract only a -consistent set of fields in a query, or rigidly check that all documents have -the same schema. This is a user choice. - -### Working with databases - -#### Create a new database - -```go -ctx := context.Background() -options := arangodb.CreateDatabaseOptions{ /*...*/ } -db, err := client.CreateDatabase(ctx, "myDB", &options) -if err != nil { - // handle error -} -``` - -#### Open a database - -```go -ctx := context.Background() -db, err := client.GetDatabase(ctx, "myDB", nil) -if err != nil { - // handle error -} -``` - -### Working with collections - -#### Create a collection - -```go -ctx := context.Background() -options := arangodb.CreateCollectionProperties{ /* ... */ } -col, err := db.CreateCollection(ctx, "myCollection", &options) -if err != nil { - // handle error -} -``` -#### Check if a collection exists - -```go -ctx := context.Background() -found, err := db.CollectionExists(ctx, "myCollection") -if err != nil { - // handle error -} -``` - -#### Open a collection - -```go -ctx := context.Background() -col, err := db.GetCollection(ctx, "myCollection", nil) -if err != nil { - // handle error -} -``` - -### Working with documents - -#### Create a document - -```go -type MyDocument struct { - Name string `json:"name"` - Counter int `json:"counter"` -} - -doc := MyDocument{ - Name: "jan", - Counter: 23, -} -ctx := context.Background() -meta, err := col.CreateDocument(ctx, doc) -if err != nil { - // handle error -} -fmt.Printf("Created document with key '%s', revision '%s'\n", meta.Key, meta.Rev) -``` - -#### Read a document - -```go -var result MyDocument -ctx := context.Background() -meta, err := col.ReadDocument(ctx, "myDocumentKey (meta.Key)", &result) -if err != nil { - // handle error -} -``` - -#### Read a document with an explicit revision - -```go -var doc MyDocument -ctx := context.Background() -options := arangodb.CreateDatabaseOptions{ - IfMatch: "mySpecificRevision (meta.Rev)", -} -meta, err := col.ReadDocumentWithOptions(revCtx, "myDocumentKey (meta.Key)", &doc, &options) -if err != nil { - // handle error -} -``` - -#### Delete a document - -```go -ctx := context.Background() -meta, err := col.DeleteDocument(ctx, myDocumentKey) -if err != nil { - // handle error -} -``` - -#### Delete a document with an explicit revision - -```go -ctx := context.Background() -options := arangodb.CollectionDocumentDeleteOptions{ - IfMatch: "mySpecificRevision (meta.Rev)", -} -meta, err := col.DeleteDocumentWithOptions(ctx, myDocumentKey, &options) -if err != nil { - // handle error -} -``` - -#### Update a document - -```go -ctx := context.Background() -patch := map[string]interface{}{ - "name": "Frank", -} -meta, err := col.UpdateDocument(ctx, myDocumentKey, patch) -if err != nil { - // handle error -} -``` - -### Working with AQL - -#### Query documents, one document at a time - -```go -ctx := context.Background() -query := "FOR d IN myCollection LIMIT 10 RETURN d" -cursor, err := db.Query(ctx, query, nil) -if err != nil { - // handle error -} else { - defer cursor.Close() - for cursor.HasMore() { - var doc MyDocument - meta, err := cursor.ReadDocument(ctx, &doc) - if err != nil { - // handle error - } else { - fmt.Printf("Got doc with key '%s' from query, name = %s\n", meta.Key, doc.Name) - } - } -} -``` - -#### Query documents, fetching the total count - -```go -ctx := context.Background() -options := arangodb.QueryOptions{ - Count: true, -} - -query := "FOR d IN myCollection RETURN d" -cursor, err := db.Query(ctx, query, &options) -if err != nil { - // handle error -} else { - defer cursor.Close() - fmt.Printf("Query yields %d documents\n", cursor.Count()) -} -``` - -#### Query documents, with bind variables - -```go -ctx := context.Background() -options := arangodb.QueryOptions{ - Count: true, - BindVars: map[string]interface{}{ - "myVar": "Some name", - } -} - -query := "FOR d IN myCollection FILTER d.name == @myVar RETURN d" - -cursor, err := db.Query(ctx, query, &options) -if err != nil { - // handle error -} -defer cursor.Close() -fmt.Printf("Query yields %d documents\n", cursor.Count()) -``` - -### Full example - -```go -package main - -import ( - "context" - "flag" - "fmt" - "log" - "strings" - - "github.com/arangodb/go-driver/v2/arangodb" - "github.com/arangodb/go-driver/v2/arangodb/shared" - "github.com/arangodb/go-driver/v2/connection" -) - -type User struct { - Name string `json:"name"` - Age int `json:"age"` -} - -func main() { - // Create an HTTP connection to the database - endpoint := connection.NewRoundRobinEndpoints([]string{"http://localhost:8529"}) - conn := connection.NewHttp2Connection(connection.DefaultHTTP2ConfigurationWrapper(endpoint, true)) - - auth := connection.NewBasicAuth("root", "") - err := conn.SetAuthentication(auth) - if err != nil { - log.Fatalf("Failed to set authentication: %v", err) - } - - // Create a client - client := arangodb.NewClient(conn) - ctx := context.Background() - - flag.Parse() - - var db arangodb.Database - var dbExists, collExists bool - - dbExists, err = client.DatabaseExists(ctx, "example") - - if dbExists { - fmt.Println("That db exists already") - - db, err = client.GetDatabase(ctx, "example", nil) - - if err != nil { - log.Fatalf("Failed to open existing database: %v", err) - } - } else { - db, err = client.CreateDatabase(ctx, "example", nil) - - if err != nil { - log.Fatalf("Failed to create database: %v", err) - } - } - - // Create collection - collExists, err = db.CollectionExists(ctx, "users") - - if collExists { - fmt.Println("That collection exists already") - } else { - var col arangodb.Collection - col, err = db.CreateCollection(ctx, "users", nil) - - if err != nil { - log.Fatalf("Failed to create collection: %v", err) - } - - // Create documents - users := []User{ - { - Name: "John", - Age: 65, - }, - { - Name: "Tina", - Age: 25, - }, - { - Name: "George", - Age: 31, - }, - } - reader, err := col.CreateDocuments(ctx, users) - if err != nil { - log.Fatalf("Failed to create documents: %v", err) - } - - meta1, err := reader.Read() - if err != nil { - log.Fatalf("Failed to read document: %v", err) - } - meta2, err := reader.Read() - if err != nil { - log.Fatalf("Failed to read document: %v", err) - } - meta3, err := reader.Read() - if err != nil { - log.Fatalf("Failed to read document: %v", err) - } - - keys := []string{meta1.Key, meta2.Key, meta3.Key} - - fmt.Printf("Created documents with keys '%s' in collection '%s' in database '%s'\n", strings.Join(keys, ","), col.Name(), db.Name()) - } - PrintCollection(db) -} - -func PrintCollection(db arangodb.Database) { - var err error - var cursor arangodb.Cursor - - querystring := "FOR doc IN users LIMIT 10 RETURN doc" - - cursor, err = db.Query(nil, querystring, nil) - - if err != nil { - log.Fatalf("Query failed: %v", err) - } - - defer cursor.Close() - - for { - var doc User - var meta arangodb.DocumentMeta - - meta, err = cursor.ReadDocument(nil, &doc) - - if shared.IsNoMoreDocuments(err) { - break - } else if err != nil { - log.Fatalf("Reading document failed: %v", err) - } else { - fmt.Printf("Metadata and document:\n%+v\n%v\n", meta, doc) - } - } -} -``` - -## API Design - -### Concurrency - -All functions of the driver are strictly synchronous. They operate and only -return a value (or error) when they are done. - -If you want to run operations concurrently, use a `go` routine. All objects in -the driver are designed to be used from multiple concurrent go routines, -except `Cursor`. - -All database objects (except `Cursor`) are considered static. After their -creation, they don't change. For example, after creating a `Collection` instance, -you can remove the collection, but the (Go) instance will still be there. Calling -functions on such a removed collection will, of course, fail. - -### Structured error handling & wrapping - -All functions of the driver that can fail return an error value. If that value -is not `nil`, the function call is considered to have failed. In that case, all -other return values are set to their zero values. - -All errors are structured using error-checking functions named -`Is`. For example, `IsNotFound(error)` returns true if the -given error is of the category "not found". There can be multiple internal error -codes that all map onto the same category. - -All errors returned from any function of the driver (either internal or exposed) -wrap errors using the `WithStack` function. This can be used to provide detailed -stack traces in case of an error. All error-checking functions use the `Cause` -function to get the cause of an error instead of the error wrapper. - -### Context-aware - -All functions of the driver that involve some kind of long-running operation or -support additional options are not given as function arguments have a -`context.Context` argument. This enables you to cancel running requests, pass -timeouts/deadlines, and pass additional options. - -## Connection management - -### Secure connections (TLS) - -The driver supports endpoints that use TLS using the `https` URL scheme. -Supplying endpoints that start with `https://` instead of `http://` is all you -need to do to use an encrypted connection. - -If you want to connect to a server that has a secure endpoint using a -**self-signed certificate**, you need to skip the certificate verification. - -```go -endpoint := connection.NewRoundRobinEndpoints([]string{"https://localhost:8529"}) -conn := connection.NewHttp2Connection(connection.DefaultHTTP2ConfigurationWrapper(endpoint, /*InsecureSkipVerify*/ true)) -``` - -### Endpoints management - -The driver supports multiple endpoints to connect to. -Currently, Maglev and RoundRobin approaches are supported. - -The following example shows how to connect to a cluster of three servers -using RoundRobin: - -```go -endpoint := connection.NewRoundRobinEndpoints([]string{"http://server1:8529", "http://server2:8529", "http://server3:8529"}) -conn := connection.NewHttp2Connection(connection.DefaultHTTP2ConfigurationWrapper(endpoint, false)) -``` - -Note that a valid endpoint is a URL to either a standalone server or a URL to a -Coordinator in a cluster. - -#### Exact behavior - -The driver monitors the request being sent to a specific server (endpoint). -As soon as the request has been completely written, failover will no longer -happen. The reason for that is that several operations cannot be (safely) retried. -For example, when a request to create a document has been sent to a server, and -a timeout occurs, the driver has no way of knowing if the server did or did not -create the document in the database. - -If the driver detects that a request has been completely written but still gets -an error (other than an error response from ArangoDB itself), it wraps the error -in a `ResponseError`. The client can test for such an error using `IsResponseError`. - -If a client receives a `ResponseError`, it can do one of the following: - -- Retry the operation and be prepared for some kind of duplicate record or - unique constraint violation. -- Perform a test operation to see if the "failed" operation did succeed after all. -- Simply consider the operation failed. This is risky since it can still be the - case that the operation did succeed. - -#### Timeouts - -To control the timeout of any function in the driver, you must pass it a context -configured with `context.WithTimeout` (or `context.WithDeadline`). - -In the case of multiple endpoints, the actual timeout used for requests is -shorter than the timeout given in the context. The driver divides the timeout by -the number of endpoints with a maximum of `3`. This ensures that the driver can -try up to 3 different endpoints (in case of failover) without being canceled due -to the timeout given by the client. Examples: - -- With 1 endpoint and a given timeout of 1 minute, the actual request timeout is 1 minute. -- With 3 endpoints and a given timeout of 1 minute, the actual request timeout is 20 seconds. -- With 8 endpoints and a given timeout of 1 minute, the actual request timeout is 20 seconds. - -For most requests, you want an actual request timeout of at least 30 seconds. diff --git a/site/content/arangodb/3.13/develop/drivers/java/_index.md b/site/content/arangodb/3.13/develop/drivers/java/_index.md deleted file mode 100644 index dc7d37d9fd..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/java/_index.md +++ /dev/null @@ -1,480 +0,0 @@ ---- -title: ArangoDB Java driver -menuTitle: Java driver -weight: 10 -description: '' ---- -The official ArangoDB Java Driver. - -- Repository: -- [Code examples](https://github.com/arangodb/arangodb-java-driver/tree/main/test-non-functional/src/test/java/example) -- [Reference](reference-version-7/_index.md) (driver setup, serialization, changes in version 7) -- [JavaDoc](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/index.html) (generated reference documentation) -- [ChangeLog](https://github.com/arangodb/arangodb-java-driver/blob/main/ChangeLog.md) - -## Supported versions - -Version 7 is the latest supported and actively developed release. - -The driver is compatible with all supported stable versions of ArangoDB server, see -[Product Support End-of-life Announcements](https://arangodb.com/subscriptions/end-of-life-notice/). - -The driver is compatible with JDK 8 and higher versions. - -{{< warning >}} -Version 6 reached End of Life (EOL) and is not actively developed anymore. -Upgrading to version 7 is recommended. - -The API changes between version 6 and 7 are documented in -[Changes in version 7](reference-version-7/changes-in-version-7.md). -{{< /warning >}} - -## Project configuration - -To use the ArangoDB Java driver, you need to import `arangodb-java-driver` as a -library into your project. This is described below for the popular Java build -automation systems Maven and Gradle. - -### Maven - -To add the driver to your project with Maven, add the following code to your -`pom.xml`: - -```xml - - - com.arangodb - arangodb-java-driver - 7.x.x - - -``` - -Substitute `7.x.x` with the latest driver version. - -### Gradle - -To add the driver to your project with Gradle, add the following code to your -`build.gradle` (substitute `7.x.x` with the latest driver version): - -```groovy -repositories { - mavenCentral() -} - -dependencies { - implementation 'com.arangodb:arangodb-java-driver:7.x.x' -} -``` - -## Tutorial - -### Connect to ArangoDB - -Let's configure and open a connection to ArangoDB. The default connection is to -`127.0.0.1:8529`. Change the connection details to point to your specific instance. - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .host("localhost", 8529) - .user("root") - .password("") - .build(); -``` - -For more connections options and details, see -[Driver setup](reference-version-7/driver-setup.md). - -### Create a database - -Let's create a new database: - -```java -ArangoDatabase db = arangoDB.db("mydb"); -System.out.println("Creating database..."); -db.create(); -``` - -### Create a collection - -Now let's create our first collection: - -```java -ArangoCollection collection = db.collection("firstCollection"); -System.out.println("Creating collection..."); -collection.create(); -``` - -### Create a document - -Let's create a document in the collection. Any object can be added as a document -to the database and be retrieved from the database as an object. - -This example uses the `BaseDocument` class, provided with the driver. The -attributes of the document are stored in a map as `key`/`value` pair: - -```java -String key = "myKey"; -BaseDocument doc = new BaseDocument(key); -doc.addAttribute("a", "Foo"); -doc.addAttribute("b", 42); -System.out.println("Inserting document..."); -collection.insertDocument(doc); -``` - -Some details you should know about the code: - -- The document key is passed to the `BaseDocument` constructor -- The `addAttribute()` method puts a new key/value pair into the document -- Each attribute is stored as a single key value pair in the document root - -### Read a document - -Read the created document: - -```java -System.out.println("Reading document..."); -BaseDocument readDocument = collection.getDocument(key, BaseDocument.class); -System.out.println("Key: " + readDocument.getKey()); -System.out.println("Attribute a: " + readDocument.getAttribute("a")); -System.out.println("Attribute b: " + readDocument.getAttribute("b")); -``` - -After executing this program, the console output should be: - -```text -Key: myKey -Attribute a: Foo -Attribute b: 42 -``` - -Some details you should know about the code: - -- The `getDocument()` method reads the stored document data and deserializes it - into the given class (`BaseDocument`) - -### Create a document from Jackson JsonNode - -You can also create a document from a Jackson -[JsonNode](https://fasterxml.github.io/jackson-databind/javadoc/2.13/com/fasterxml/jackson/databind/JsonNode.html) -object: - -```java -System.out.println("Creating a document from Jackson JsonNode..."); -String keyJackson = "myJacksonKey"; -JsonNode jsonNode = JsonNodeFactory.instance.objectNode() - .put("_key", keyJackson) - .put("a", "Bar") - .put("b", 53); -System.out.println("Inserting document from Jackson JsonNode..."); -collection.insertDocument(jsonNode); -``` - -### Read a document as Jackson JsonNode - -You can also read a document as a Jackson -[JsonNode](https://fasterxml.github.io/jackson-databind/javadoc/2.13/com/fasterxml/jackson/databind/JsonNode.html): - -```java -System.out.println("Reading document as Jackson JsonNode..."); -JsonNode readJsonNode = collection.getDocument(keyJackson, JsonNode.class); -System.out.println("Key: " + readJsonNode.get("_key").textValue()); -System.out.println("Attribute a: " + readJsonNode.get("a").textValue()); -System.out.println("Attribute b: " + readJsonNode.get("b").intValue()); -``` - -After executing this program, the console output should be: - -```text -Key: myKey -Attribute a: Bar -Attribute b: 53 -``` - -Some details you should know about the code: - -- The `getDocument()` method returns the stored document as instance of - `com.fasterxml.jackson.databind.JsonNode`. - -### Create a document from JSON String - -You can also create a document from raw JSON string: - -```java -System.out.println("Creating a document from JSON String..."); -String keyJson = "myJsonKey"; -RawJson json = RawJson.of("{\"_key\":\"" + keyJson + "\",\"a\":\"Baz\",\"b\":64}"); -System.out.println("Inserting document from JSON String..."); -collection.insertDocument(json); -``` - -### Read a document as JSON String - -You can also read a document as raw JSON string: - -```java -System.out.println("Reading document as JSON String..."); -RawJson readJson = collection.getDocument(keyJson, RawJson.class); -System.out.println(readJson.get()); -``` - -After executing this program, the console output should be: - -```text -{"_key":"myJsonKey","_id":"firstCollection/myJsonKey","_rev":"_e0nEe2y---","a":"Baz","b":64} -``` - -### Update a document - -Let's update the document: - -```java -doc.addAttribute("c", "Bar"); -System.out.println("Updating document ..."); -collection.updateDocument(key, doc); -``` - -### Read the document again - -Let's read the document again: - -```java -System.out.println("Reading updated document ..."); -BaseDocument updatedDocument = collection.getDocument(key, BaseDocument.class); -System.out.println("Key: " + updatedDocument.getKey()); -System.out.println("Attribute a: " + updatedDocument.getAttribute("a")); -System.out.println("Attribute b: " + updatedDocument.getAttribute("b")); -System.out.println("Attribute c: " + updatedDocument.getAttribute("c")); -``` - -After executing this program, the console output should look like this: - -```text -Key: myKey -Attribute a: Foo -Attribute b: 42 -Attribute c: Bar -``` - -### Delete a document - -Let's delete a document: - -```java -System.out.println("Deleting document ..."); -collection.deleteDocument(key); -``` - -### Execute AQL queries - -First, you need to create some documents with the name `Homer` in the -collection called `firstCollection`: - -```java -for (int i = 0; i < 10; i++) { - BaseDocument value = new BaseDocument(String.valueOf(i)); - value.addAttribute("name", "Homer"); - collection.insertDocument(value); -} -``` - -Get all documents with the name `Homer` from the collection using an AQL query -and iterate over the results: - -```java -String query = "FOR t IN firstCollection FILTER t.name == @name RETURN t"; -Map bindVars = Collections.singletonMap("name", "Homer"); -System.out.println("Executing read query ..."); -ArangoCursor cursor = db.query(query, BaseDocument.class, bindVars); -cursor.forEach(aDocument -> System.out.println("Key: " + aDocument.getKey())); -``` - -After executing this program, the console output should look something like this: - -```text -Key: 1 -Key: 0 -Key: 5 -Key: 3 -Key: 4 -Key: 9 -Key: 2 -Key: 7 -Key: 8 -Key: 6 -``` - -Some details you should know about the code: - -- The AQL query uses the placeholder `@name` that has to be bound to a value -- The `query()` method executes the defined query and returns an `ArangoCursor` - with the given class (here: `BaseDocument`) -- The order of is not guaranteed - -### Delete documents with AQL - -Delete previously created documents: - -```java -String query = "FOR t IN firstCollection FILTER t.name == @name " - + "REMOVE t IN firstCollection LET removed = OLD RETURN removed"; -Map bindVars = Collections.singletonMap("name", "Homer"); -System.out.println("Executing delete query ..."); -ArangoCursor cursor = db.query(query, BaseDocument.class, bindVars); -cursor.forEach(aDocument -> System.out.println("Removed document " + aDocument.getKey())); -``` - -After executing this program, the console output should look something like this: - -```text -Removed document: 1 -Removed document: 0 -Removed document: 5 -Removed document: 3 -Removed document: 4 -Removed document: 9 -Removed document: 2 -Removed document: 7 -Removed document: 8 -Removed document: 6 -``` - -### Learn more - -- Have a look at the [AQL documentation](../../../aql/) to lear about the - query language -- See [Serialization](reference-version-7/serialization.md) for details about - user-data serde -- For the full reference documentation, see - [JavaDoc](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/index.html) - -## GraalVM Native Image - -The driver supports GraalVM Native Image compilation. -To compile with `--link-at-build-time` when `http-protocol` module is present in -the classpath, additional substitutions are required for transitive dependencies -`Netty` and `Vert.x`. See this -[example](https://github.com/arangodb/arangodb-java-driver/tree/main/test-functional/src/test-default/java/graal) -for reference. Such substitutions are not required when compiling the shaded driver. - -### Framework compatibility - -The driver can be used in the following frameworks that support -GraalVM Native Image generation: - -- [Quarkus](https://quarkus.io), see [arango-quarkus-native-example](https://github.com/arangodb-helper/arango-quarkus-native-example) -- [Helidon](https://helidon.io), see [arango-helidon-native-example](https://github.com/arangodb-helper/arango-helidon-native-example) -- [Micronaut](https://micronaut.io), see [arango-micronaut-native-example](https://github.com/arangodb-helper/arango-micronaut-native-example) - -## ArangoDB Java Driver Shaded - -A shaded variant of the driver is also published with -Maven coordinates: `com.arangodb:arangodb-java-driver-shaded`. - -It bundles and relocates the following packages: -- `com.fasterxml.jackson` -- `com.arangodb.jackson.dataformat.velocypack` -- `io.vertx` -- `io.netty` - -Note that the **internal serde** internally uses Jackson classes from -`com.fasterxml.jackson` that are relocated to `com.arangodb.shaded.fasterxml.jackson`. -Therefore, the **internal serde** of the shaded driver is not compatible with -Jackson annotations and modules from package`com.fasterxml.jackson`, but only -with their relocated variants. In case the **internal serde** is used as -**user-data serde**, the annotations from package `com.arangodb.serde` can be -used to annotate fields, parameters, getters and setters for mapping values -representing ArangoDB documents metadata (`_id`, `_key`, `_rev`, `_from`, `_to`): -- `@InternalId` -- `@InternalKey` -- `@InternalRev` -- `@InternalFrom` -- `@InternalTo` - -These annotations are compatible with relocated Jackson classes. -Note that the **internal serde** is not part of the public API and could change -in future releases without notice, thus breaking client applications relying on -it to serialize or deserialize user-data. It is therefore recommended also in -this case either: -- using the default user-data serde `JacksonSerde` - (from packages `com.arangodb:jackson-serde-json` or `com.arangodb:jackson-serde-vpack`), or -- providing a custom user-data serde implementation via `ArangoDB.Builder.serde(ArangoSerde)`. - -## Support for extended naming constraints - -The driver supports ArangoDB's **extended** naming constraints/convention, -allowing most UTF-8 characters in the names of: -- Databases -- Collections -- Views -- Indexes - -These names must be NFC-normalized, otherwise the server returns an error. -To normalize a string, use the function -`com.arangodb.util.UnicodeUtils.normalize(String): String`: - -```java -String normalized = UnicodeUtils.normalize("𝔸𝕣𝕒𝕟𝕘𝕠𝔻𝔹"); -``` - -To check if a string is already normalized, use the -function `com.arangodb.util.UnicodeUtils.isNormalized(String): boolean`: - -```java -boolean isNormalized = UnicodeUtils.isNormalized("𝔸𝕣𝕒𝕟𝕘𝕠𝔻𝔹"); -``` - -## Async API - -The asynchronous API is accessible via `ArangoDB#async()`, for example: - -```java -ArangoDB adb = new ArangoDB.Builder() - // ... - .build(); -ArangoDBAsync adbAsync = adb.async(); -CompletableFuture version = adbAsync.getVersion(); -// ... -``` - -Under the hood, both synchronous and asynchronous API use the same internal -communication layer, which has been reworked and re-implemented in an -asynchronous way. The synchronous API blocks and waits for the result, while the -asynchronous one returns a `CompletableFuture<>` representing the pending -operation being performed. -Each asynchronous API method is equivalent to the corresponding synchronous -variant, except for the Cursor API. - -### Async Cursor API - -The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different, -because the synchronous Cursor API is based on Java's `java.util.Iterator`, which -is an interface only suitable for synchronous scenarios. -On the other side, the asynchronous Cursor API provides a method -`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a -`CompletableFuture>` and can be used to consume the next -batch of the cursor, for example: - -```java -CompletableFuture> future1 = adbAsync.db() - .query("FOR i IN i..10000", Integer.class); -CompletableFuture> future2 = future1 - .thenCompose(c -> { - List batch = c.getResult(); - // ... - // consume batch - // ... - return c.nextBatch(); - }); -// ... -``` - -## Data Definition Classes - -Classes used to exchange data definitions, in particular classes in the packages -`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized -and deserialized internally by the driver. - -The behavior to serialize and deserialize these classes is considered an internal -implementation detail, and as such, it might change without prior notice. -The API with regard to the public members of these classes is kept compatible. diff --git a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/_index.md b/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/_index.md deleted file mode 100644 index 52f8726704..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: ArangoDB Java Driver version 7 -menuTitle: Reference version 7 -weight: 5 -description: >- - The official ArangoDB Java Driver version 7 ---- diff --git a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/changes-in-version-7.md b/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/changes-in-version-7.md deleted file mode 100644 index f960b5b5a0..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/changes-in-version-7.md +++ /dev/null @@ -1,448 +0,0 @@ ---- -title: Changes in version 7 -menuTitle: Changes in version 7 -weight: 15 -description: >- - Various detailed have changed, like the setup, transport, configuration, - serialization, and some of the APIs ---- -## Maven Setup - -```xml - - - com.arangodb - arangodb-java-driver - 7.x.x - - -``` - -Substitute `7.x.x` with the latest available driver version. - -## Gradle Setup - -```groovy -repositories { - mavenCentral() -} - -dependencies { - implementation 'com.arangodb:arangodb-java-driver:7.x.x' -} -``` - -## HTTP client - -The HTTP client has been changed to [Vert.x WebClient](https://vertx.io/docs/vertx-web-client/java/). - -`HTTP/2` is now supported. -`HTTP/2` supports multiplexing and uses `1` connection per host by default. - -Cookies are not supported anymore: cookies received in the response are ignored. - -## Configuration changes - -The default communication protocol is now `HTTP2_JSON` (`HTTP/2` with `JSON` content type). - -The default host configuration to `127.0.0.1:8529` has been removed. - -Configuration properties are not read automatically from properties files anymore. -A new API for loading properties has been introduced: -`ArangoDB.Builder.loadProperties(ArangoConfigProperties)`. -Implementations can supply configuration properties coming from different sources, -like system properties, remote stores, frameworks integrations, etc. -An implementation for loading properties from local files is provided by -`ArangoConfigProperties.fromFile()` and its overloaded variants. - -Example of how to read config properties prefixed with `arangodb` from -`arangodb.properties` file (as in version `6`): - -```java -// ## src/main/resources/arangodb.properties -// arangodb.hosts=172.28.0.1:8529 -// arangodb.password=test -// ... - -ArangoConfigProperties props = ArangoConfigProperties.fromFile(); -``` - -To read config properties from `arangodb-with-prefix.properties` file, where the -config properties are prefixed with `adb`: - -```java -// ## src/main/resources/arangodb-with-prefix.properties -// adb.hosts=172.28.0.1:8529 -// adb.password=test -// ... - -ArangoConfigProperties props = ArangoConfigProperties.fromFile("arangodb-with-prefix.properties", "adb"); -``` - -See the related reference documentation about -[Config File Properties](driver-setup.md#config-file-properties) -for details. - -Examples showing how to provide configuration properties from different sources: -- [Eclipse MicroProfile Config](https://github.com/arangodb-helper/arango-quarkus-native-example/blob/master/src/main/java/com/arangodb/ArangoConfig.java) -- [Micronaut Configuration](https://github.com/arangodb-helper/arango-micronaut-native-example/blob/main/src/main/kotlin/com/example/ArangoConfig.kt) - -## Modules - -Support for different serdes and communication protocols is offered by separate modules. -Default modules are transitively included, but they could be excluded if not needed. - -The main driver artifact `com.arangodb:arangodb-java-driver` has transitive dependencies on default modules: -- `com.arangodb:http-protocol`: `HTTP` communication protocol (HTTP/1.1 and HTTP/2) -- `com.arangodb:jackson-serde-json`: `JSON` user-data serde module based on Jackson Databind - -Alternative module for user-data serde: -- `com.arangodb:jackson-serde-vpack`: `VPACK` user-data serde module based on Jackson Databind - -The modules above are discovered and loaded using SPI (Service Provider Interface). - -In case a non-default communication protocol or user serde are used, the related module(s) -must be explicitly included and the corresponding default module(s) can be excluded. - -For example, to use the driver with `VPACK` over `HTTP`: - -- You must include `com.arangodb:jackson-serde-vpack` -- You can exclude `com.arangodb:jackson-serde-json` -- You don't need to include `com.arangodb:http-protocol` because the driver - includes it automatically - -For example in Maven: - -```xml - - - com.arangodb - arangodb-java-driver - - - com.arangodb - jackson-serde-json - - - - - com.arangodb - jackson-serde-vpack - - -``` - -## Transitive dependencies - -`com.arangodb:arangodb-java-driver` has transitive dependencies on `jackson-core`, -`jackson-databind`, and `jackson-annotations`, using by default version `2.14`. - -The versions of such libraries can be overridden. -The driver is compatible with Jackson 2 (at least `2.10` or greater). - -To do this, you might need to include [jackson-bom](https://github.com/FasterXML/jackson-bom) -to ensure dependency convergence across the entire project, for example in case -there are in your project other libraries depending on different versions of Jackson: - -```xml - - - - com.fasterxml.jackson - jackson-bom - x.y.z - import - pom - - - -``` - -Substitute `x.y.z` with the latest stable version. - -The module `http-protocol` has transitive dependency on `io.vertx:vertx-web-client`, -which in turn depends on packages from `io.netty`. - -If these dependency requirements cannot be satisfied, i.e. they cause convergence -conflicts with other versions of same packages in the classpath, you might need -to use the [shaded version](#arangodb-java-driver-shaded) of this driver, which -bundles all modules together with relocated external dependencies. - -The dependency on `com.arangodb:velocypack` has been removed from core module and -is now only used as internal dependency by `com.arangodb:jackson-serde-vpack`, -thus transitively imported only when using `VPACK` content type. - -## User Data - -Before version 7.0, the driver always parsed raw strings as JSON, but unfortunately -this did not allow to distinguish it from the case when the intent is to use the -raw string as such, without parsing it. From version 7.0 onward, strings are not -interpreted as JSON anymore. To represent user-data as raw JSON, the wrapper -class `com.arangodb.util.RawJson` has been added: - -```java -RawJson rawJsonIn = RawJson.of(""" - {"foo":"bar"} - """); -ArangoCursor res = adb.db().query("RETURN @v", RawJson.class, Map.of("v", rawJsonIn)); -RawJson rawJsonOut = res.next(); -String json = rawJsonOut.get(); // {"foo":"bar"} -``` - -To represent user-data already encoded as byte array, the wrapper class `RawBytes` -has been added. The byte array can either represent a `JSON` string (UTF-8 encoded) -or a `VPACK` value. The format used should match the driver protocol configuration -(`JSON` for `HTTP_JSON` and `HTTP2_JSON`, otherwise `VPACK`). - -The following changes have been applied to `com.arangodb.entity.BaseDocument` -and `com.arangodb.entity.BaseEdgeDocument`: -- new method `removeAttribute(String)` -- `getProperties()` returns an unmodifiable map - -Before version 7.0, when performing write operations, the metadata of the input -data objects was updated in place with the metadata received in the response. -From version 7.0 onward, the input data objects passed as arguments to API methods -are treated as immutable and the related metadata fields are not updated anymore. -The updated metadata can be found in the returned object. - -## Serialization / Deserialization - -Up to version 6, the (de)serialization was always performed to/from `VPACK`. -In case the JSON format was required, the raw `VPACK` was then converted to `JSON`. -From version 7 onward, the serialization module is a dataformat-agnostic API. -Implementations can serialize and deserialize directly to the target dataformat, -without intermediate conversion to `VPACK`. The default implementation uses the -`JSON` format. - -Support for data type `VPackSlice` has been removed in favor of Jackson type -`com.fasterxml.jackson.databind.JsonNode` and its subclasses -(`ArrayNode`, `ObjectNode`, ...), for example: - -```java -JsonNode jsonNodeIn = JsonNodeFactory.instance - .objectNode() - .put("foo", "bar"); - -ArangoCursor res = adb.db().query("RETURN @v", JsonNode.class, Map.of("v", jsonNodeIn)); -JsonNode jsonNodeOut = res.next(); -String foo = jsonNodeOut.get("foo").textValue(); // bar -``` - -The dependency on `com.arangodb:velocypack` has been removed. Since version 3.0, -`com.arangodb:velocypack` does not include databind functionalities anymore. -It only offers a lower level API to deal with primitive `VPACK` types. -`VPACK` databind functionalities are now offered by -[`jackson-dataformat-velocypack`](https://github.com/arangodb/jackson-dataformat-velocypack), -which is a Jackson backend for `VPACK` dataformat. - -The user-data custom serializer implementation `ArangoJack` has been removed in -favor of `com.arangodb.serde.jackson.JacksonSerde`. This allows using Jackson API -to serialize and deserialize user-data, compatible with both `JSON` and `VPACK`. - -See the detailed documentation about [Serialization](serialization.md) -for more information. - -## ArangoDB Java Driver Shaded - -From version 7 onward, a shaded variant of the driver is also published with -Maven coordinates: `com.arangodb:arangodb-java-driver-shaded`. - -It bundles and relocates the following packages: -- `com.fasterxml.jackson` -- `com.arangodb.jackson.dataformat.velocypack` -- `io.vertx` -- `io.netty` - -Note that the **internal serde** internally uses Jackson classes from -`com.fasterxml.jackson` that are relocated to `com.arangodb.shaded.fasterxml.jackson`. -Therefore, the **internal serde** of the shaded driver is not compatible with -Jackson annotations and modules from package`com.fasterxml.jackson`, but only -with their relocated variants. In case the **internal serde** is used as -**user-data serde**, the annotations from package `com.arangodb.serde` can be -used to annotate fields, parameters, getters and setters for mapping values -representing ArangoDB documents metadata (`_id`, `_key`, `_rev`, `_from`, `_to`): -- `@InternalId` -- `@InternalKey` -- `@InternalRev` -- `@InternalFrom` -- `@InternalTo` - -These annotations are compatible with relocated Jackson classes. -Note that the **internal serde** is not part of the public API and could change -in future releases without notice, thus breaking client applications relying on -it to serialize or deserialize user-data. It is therefore recommended also in -this case either: -- using the default user-data serde `JacksonSerde` (from packages `com.arangodb:jackson-serde-json` or -`com.arangodb:jackson-serde-vpack`), or -- providing a custom user-data serde implementation via `ArangoDB.Builder.serde(ArangoSerde)`. - -## Removed APIs - -The following client APIs have been removed: - -- client APIs already deprecated in Java Driver version `6` -- client API to interact with deprecated server APIs: - - `MMFiles` related APIs - - `ArangoDatabase.executeTraversal()` - - `ArangoDB.getLogs()` - - `minReplicationFactor` in collections and graphs - - `overwrite` flag in `DocumentCreateOptions` - - `hash` and `skipList` indexes - -The user-data custom serializer implementation `ArangoJack` has been removed in -favor of `com.arangodb.serde.jackson.JacksonSerde`. - -Support for interpreting raw strings as JSON has been removed -(in favor of `com.arangodb.util.RawJson`). - -Support of data type `com.arangodb.velocypack.VPackSlice` has been removed in -favor of Jackson type `com.fasterxml.jackson.databind.JsonNode` and its subclasses -(`ArrayNode`, `ObjectNode`, ...). Raw `VPACK` data can now be used with -`com.arangodb.util.RawBytes`. - -Support for custom initialization of cursors -(`ArangoDB._setCursorInitializer(ArangoCursorInitializer cursorInitializer)`) -has been removed. - -## Async API - -From version 7.2 onward, the driver provides a new asynchronous API. -Unlike in version 6, the asynchronous API is based on the same underlying driver -instance and therefore supports all the communication protocols and configurations -of the synchronous API. The asynchronous API is accessible via `ArangoDB#async()`, -for example: - -```java -ArangoDB adb = new ArangoDB.Builder() - // ... - .build(); -ArangoDBAsync adbAsync = adb.async(); -CompletableFuture version = adbAsync.getVersion(); -// ... -``` - -Under the hood, both synchronous and asynchronous API use the same internal -communication layer, which has been reworked and re-implemented in an -asynchronous way. The synchronous API blocks and waits for the result, while the -asynchronous one returns a `CompletableFuture<>` representing the pending -operation being performed. -Each asynchronous API method is equivalent to the corresponding synchronous -variant, except for the Cursor API. - -### Async Cursor API - -The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different, -because the synchronous Cursor API is based on Java's `java.util.Iterator`, which -is an interface only suitable for synchronous scenarios. -On the other side, the asynchronous Cursor API provides a method -`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a -`CompletableFuture>` and can be used to consume the next -batch of the cursor, for example: - -```java -CompletableFuture> future1 = adbAsync.db() - .query("FOR i IN i..10000", Integer.class); -CompletableFuture> future2 = future1 - .thenCompose(c -> { - List batch = c.getResult(); - // ... - // consume batch - // ... - return c.nextBatch(); - }); -// ... -``` - -## API methods changes - -Before version 7.0, some CRUD API methods inferred the return type from the type -of the data object passed as input. Now, the return type can be explicitly set -for each CRUD API method. This type is used as deserialization target by the -user-data serde. In particular, no automatic type inference is performed anymore in: -- `ArangoCollection.insertDocuments()` -- `ArangoCollection.replaceDocuments()` -- `ArangoCollection.updateDocuments()` -- `ArangoCollection.deleteDocuments()` - -Unless specified explicitly, the target deserialization type is `Void.class`, -thus allowing only `null` values. - -CRUD operations operating with multiple documents have now an overloaded variant -which accepts raw data (`RawBytes` and `RawJson`) containing multiple documents. - -CRUD operations operating with multiple documents with parametric types are now covariant: -- `ArangoCollection.insertDocuments(Collection, DocumentCreateOptions, Class)` -- `ArangoCollection.replaceDocuments(Collection, DocumentReplaceOptions, Class)` - -`com.arangodb.Request` and `com.arangodb.Response` classes have been refactored -to support generic body type. `ArangoDB.execute(Request, Class): Response` -accepts now the target deserialization type for the response body. - -`com.arangodb.ArangoDBException` has been enhanced with the id of the request -causing it. This can be useful to correlate it with the debug level logs. - -Graph API has been updated (#486): -- added `com.arangodb.ArangoEdgeCollection.drop()` and overloads -- added `com.arangodb.ArangoVertexCollection.drop(VertexCollectionDropOptions)` -- updated `com.arangodb.ArangoGraph.replaceEdgeDefinition()` - -`ArangoDatabase.getDocument()` has been removed, in favor of `ArangoCollection.getDocument()`. - -`ArangoDatabase.query()` overloaded variants have now a different order of parameters: -- `query(String query, Class type)` -- `query(String query, Class type, AqlQueryOptions options)` -- `query(String query, Class type, Map bindVars)` -- `query(String query, Class type, Map bindVars, AqlQueryOptions options)` - -The class `com.arangodb.DbName` has been removed. The database names can now be -passed as `String`. Support to UTF-8 characters in data definition names -(databases, collections, Views, indexes) has been added, see -[Support for extended naming constraints](../_index.md#support-for-extended-naming-constraints). - -The name of `ArangoCollection` and `ArangoView` API classes are now final. -The related rename methods: -- `com.arangodb.ArangoCollection.rename(String)` -- `com.arangodb.ArangoView.rename(String)` - -Do not change anymore the collection or view name of the instance of the related -API class on which it is invoked. To interact with the renamed collection, a new -instance of `ArangoCollection` with the new name must be created. - -## API entities - -All entities and options classes (in packages `com.arangodb.model` and -`com.arangodb.entity`) are now `final`. - -The replication factor is now modeled with a new interface -(`com.arangodb.entity.ReplicationFactor`) with implementations: -`NumericReplicationFactor` and `SatelliteReplicationFactor`. - -Cursor statistics are now in `com.arangodb.entity.CursorStats`. - -## GraalVM Native Image - -The driver supports GraalVM Native Image compilation. -To compile with `--link-at-build-time` when `http-protocol` module is present in -the classpath, additional substitutions are be required for its transitive -dependencies (`Netty` and `Vert.x`). See this -[example](https://github.com/arangodb/arangodb-java-driver/tree/main/test-functional/src/test-default/java/graal) -for reference. Such substitutions are not required when compiling the shaded driver. - -### Framework compatibility - -The driver can be used in the following frameworks that support -GraalVM Native Image generation: - -- [Quarkus](https://quarkus.io), see [arango-quarkus-native-example](https://github.com/arangodb-helper/arango-quarkus-native-example) -- [Helidon](https://helidon.io), see [arango-helidon-native-example](https://github.com/arangodb-helper/arango-helidon-native-example) -- [Micronaut](https://micronaut.io), see [arango-micronaut-native-example](https://github.com/arangodb-helper/arango-micronaut-native-example) - -## Migration - -To migrate your existing project to Java Driver version 7.0, it is recommended -first updating to the latest version of branch `6` and make sure that your code -does not use any deprecated API. This can be done by checking the presence of -deprecation warnings in the Java compiler output. - -The deprecation notes in the related JavaDoc contain information about the -reason of the deprecation and suggest migration alternatives to use. diff --git a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/driver-setup.md b/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/driver-setup.md deleted file mode 100644 index 6972a542de..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/driver-setup.md +++ /dev/null @@ -1,300 +0,0 @@ ---- -title: Driver setup -menuTitle: Driver Setup -weight: 5 -description: >- - How to connect your Java application to an ArangoDB server, as well as - important configuration settings and information about the driver ---- -The driver can be configured and instantiated using `com.arangodb.ArangoDB.Builder`: - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - // ... - .build(); -``` - -To customize the configuration properties can be set programmatically in the builder: - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .host("127.0.0.1",8529) - // ... - .build(); -``` - -or providing an implementation of `com.arangodb.config.ArangoConfigProperties` -to the builder: - -```java -ArangoConfigProperties props = ... -ArangoDB arangoDB = new ArangoDB.Builder() - .loadProperties(props) - // ... - .build(); -``` - -Implementations of `com.arangodb.config.ArangoConfigProperties` could supply -configuration properties coming from different sources, eg. system properties, -remote stores, frameworks integrations, etc. -An implementation for loading properties from local files is provided by -`ArangoConfigProperties.fromFile()` and its overloaded variants. - -To read config properties prefixed with `arangodb` from `arangodb.properties` -file: - -```java -// ## src/main/resources/arangodb.properties -// arangodb.hosts=172.28.0.1:8529 -// arangodb.password=test -// ... - -ArangoConfigProperties props = ArangoConfigProperties.fromFile(); -``` - -To read config properties from `arangodb-with-prefix.properties` file, where the -config properties are prefixed with `adb`: - -```java -// ## src/main/resources/arangodb-with-prefix.properties -// adb.hosts=172.28.0.1:8529 -// adb.password=test -// ... - -ArangoConfigProperties props = ArangoConfigProperties.fromFile("arangodb-with-prefix.properties", "adb"); -``` - -Here are examples to integrate configuration properties from different sources: -- [Eclipse MicroProfile Config](https://github.com/arangodb-helper/arango-quarkus-native-example/blob/master/src/main/java/com/arangodb/ArangoConfig.java) -- [Micronaut Configuration](https://github.com/arangodb-helper/arango-micronaut-native-example/blob/main/src/main/kotlin/com/example/ArangoConfig.kt) - -## Configuration - -`ArangoDB.Builder` has the following configuration methods: - -- `host(String, int)`: Adds a host (hostname and port) to connect to, multiple hosts can be added -- `protocol(Protocol)`: Communication protocol, possible values are: `HTTP_JSON`, `HTTP_VPACK`, `HTTP2_JSON`, `HTTP2_VPACK`, `VST` (unsupported from ArangoDB v3.12 onward), (default: `HTTP2_JSON`) -- `timeout(Integer)`: Connection and request timeout (ms), (default `0`, no timeout) -- `user(String)`: Username for authentication, (default: `root`) -- `password(String)`: Password for authentication -- `jwt(String)`: JWT for authentication -- `useSsl(Boolean)`: Use SSL connection, (default: `false`) -- `sslContext(SSLContext)`: SSL context -- `sslCertValue(String)`: SSL certificate value as Base64-encoded String -- `sslAlgorithm(String)`: Name of the SSL Trust manager algorithm (default: `SunX509`) -- `sslProtocol(String)`: Name of the SSLContext protocol (default: `TLS`) -- `verifyHost(Boolean)`: Enable hostname verification, (HTTP only, default: `true`) -- `maxConnections(Integer)`: Max number of connections per host, (default: `1` for `HTTP/2`, `20` for `HTTP/1.1`) -- `connectionTtl(Long)`: Time to live of an inactive connection (ms), (default: `30_000`) -- `acquireHostList(Boolean)`: Acquire the list of available hosts, (default: `false`) -- `acquireHostListInterval(Integer)`: The interval for acquiring the host list (ms), (default: `3_600_000`, 1 hour) -- `loadBalancingStrategy(LoadBalancingStrategy)`: Load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`) -- `responseQueueTimeSamples(Integer)`: Amount of samples kept for queue time metrics, (default: `10`) -- `compression(Compression)`: The `content-encoding` and `accept-encoding` to use for HTTP requests, possible values are: `NONE`, `DEFLATE`, `GZIP`, (default: `NONE`) -- `compressionThreshold(Integer)`: The minimum HTTP request body size (in bytes) to trigger compression, (default: `1024`) -- `compressionLevel`: Compression level between 0 and 9, (default: `6`) -- `serde(ArangoSerde)`: Serde to serialize and deserialize user-data -- `serdeProviderClass(Class)`: Serde provider to be used to instantiate the user-data serde -- `protocolConfig(ProtocolConfig)`: Configuration specific for the used protocol provider implementation -- `pipelining(Boolean):`: Use HTTP pipelining, (`HTTP/1.1` only, default `false`) - -### HTTP Protocol Provider Configuration - -The `ProtocolConfig` for the default HTTP protocol provider can be created via: - -```java -HttpProtocolConfig.builder() - // ... - .build(); -``` - -and configured using the following builder methods: - -- `vertx(Vertx)`: Vert.x instance to use. If not set, a new instance is created. - -For example, to reuse the existing Vert.x instance: - -```java -HttpProtocolConfig.builder() - .protocolConfig(HttpProtocolConfig.builder() - .vertx(Vertx.currentContext().owner()) - .build() - ) - .build(); -``` - -### Config File Properties - -`ArangoConfigProperties.fromFile()` reads config properties prefixed with `arangodb` -from `arangodb.properties` file. Different prefix and -file name can be specified using its overloaded variants. - -The properties read are: -- `hosts`: comma-separated list of `:` entries -- `protocol`: `HTTP_JSON`, `HTTP_VPACK`, `HTTP2_JSON`, `HTTP2_VPACK`, or `VST` (unsupported from ArangoDB v3.12 onward) -- `timeout` -- `user` -- `password` -- `jwt` -- `useSsl` -- `sslCertValue`: SSL certificate as Base64-encoded string -- `sslAlgorithm`: SSL trust manager algorithm (default: `SunX509`) -- `sslProtocol`: SSLContext protocol (default: `TLS`) -- `verifyHost` -- `chunkSize` -- `maxConnections` -- `connectionTtl` -- `keepAliveInterval` -- `acquireHostList` -- `acquireHostListInterval` -- `loadBalancingStrategy`: `NONE`, `ROUND_ROBIN` or `ONE_RANDOM` -- `responseQueueTimeSamples` -- `compression`: `NONE`, `DEFLATE` or `GZIP` -- `compressionThreshold` -- `compressionLevel` -- `serdeProviderClass`: fully qualified name of the provider class -- `pipelining` - -## SSL - -To use SSL, you have to set the configuration `useSsl` to `true`. -By default, the driver uses the default `SSLContext`. -To change this, you can provide the `SSLContext` instance to use: - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .useSsl(true) - .sslContext(sc) - .build(); -``` - -Alternatively, the driver can create a new `SSLContext` using the provided -configuration. In this case, it is required to set the configuration `sslCertValue` -with the SSL certificate value as Base64-encoded String: - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .useSsl(true) - .sslCertValue("") // SSL certificate as Base64-encoded String - .sslAlgorithm("SunX509") // SSL Trust manager algorithm (optional, default: SunX509) - .sslProtocol("TLS") // SSLContext protocol (optional, default: TLS) - .build(); -``` - -See the [example code](https://github.com/arangodb/arangodb-java-driver/blob/main/test-functional/src/test-ssl/java/com/arangodb/SslExampleTest.java) -for more details on SSL configuration. - -## Connection Pooling - -The driver keeps a pool of connections for each host, the max amount of -connections is configurable. - -Inactive connections are released after the configured connection time-to-live -(`ArangoDB.Builder.connectionTtl(Long)`) or when the driver is shut down: - -```java -arangoDB.shutdown(); -``` - -## Thread Safety - -The driver can be used concurrently by multiple threads. All the following -classes are thread safe: -- `com.arangodb.ArangoDB` -- `com.arangodb.ArangoDatabase` -- `com.arangodb.ArangoCollection` -- `com.arangodb.ArangoGraph` -- `com.arangodb.ArangoVertexCollection` -- `com.arangodb.ArangoEdgeCollection` -- `com.arangodb.ArangoView` -- `com.arangodb.ArangoSearch` - -Any other class should not be considered thread safe. In particular classes -representing request options (package `com.arangodb.model`) and response entities -(package `com.arangodb.entity`) are **not** thread safe. - -## Fallback hosts - -The driver supports configuring multiple hosts. The first host is used to open a -connection to. When this host is not reachable the next host from the list is used. -To use this feature just call the method `host(String, int)` multiple times. - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .host("host1", 8529) - .host("host2", 8529) - .build(); -``` - -The driver is also able to acquire a list of known hosts in a cluster. For this the driver has -to be able to successfully open a connection to at least one host to get the -list of hosts. Then it can use this list when fallback is needed. To enable this -feature: - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .acquireHostList(true) - .build(); -``` - -## Load Balancing - -The driver supports load balancing for cluster setups in -two different ways. - -The first one is a round robin load balancing where the driver iterates -through a list of known hosts and performs every request on a different -host than the request before. - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN) - .build(); -``` - -The second load balancing strategy picks a random host from host list -(configured or acquired) and sticks to it as long as the -connection is open. - -```java -ArangoDB arangoDB = new ArangoDB.Builder() - .loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM) - .build(); -``` - -## Connection time to live - -The driver supports setting a TTL (time to live) for connections: - -```java -ArangoDB arango = new ArangoDB.Builder() - .connectionTtl(5 * 60 * 1000) // ms - .build(); -``` - -In this example, inactive connections are closed after 5 minutes. - -The default connection TTL is `30` seconds. - -If set to `null`, no automatic connection closure is performed. - -## Proxy configuration - -The driver allows configuring the underlying Vert.x WebClient to work -with HTTP proxies. The configuration is specific to the HTTP protocol -and uses the `io.vertx.core.net.ProxyOptions` class of -[Vert.x Core](https://www.javadoc.io/doc/io.vertx/vertx-core/4.5.7/io/vertx/core/net/ProxyOptions.html): - -```java -ArangoDB arango = new ArangoDB.Builder() - // ... - .protocolConfig(HttpProtocolConfig.builder() - .proxyOptions(new ProxyOptions() - .setType(ProxyType.HTTP) - .setHost("172.28.0.1") - .setPort(8888) - .setUsername("user") - .setPassword("password")) - .build()) - .build(); -``` diff --git a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/serialization.md b/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/serialization.md deleted file mode 100644 index af4dfd27f1..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/java/reference-version-7/serialization.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Serialization -menuTitle: Serialization -weight: 10 -description: >- - The Java driver uses Jackson internally for serialization and deserialization - but you can use a custom implementation for user data ---- -The driver functionalities related to serialization and deserialization (serde) -are implemented by 2 different components: -- `internal serde` -- `user-data serde` - -The **internal serde** is based on [Jackson](https://github.com/FasterXML/jackson) -API and is responsible for serializing/deserializing data definition classes -(in packages `com.arangodb.model` and `com.arangodb.entity`). -This includes all the classes that are not user-data, such as metadata properties -for databases, collections, graphs, etc. - -Furthermore, it is used to serialize and deserialize user-data of the following managed types: -- `com.fasterxml.jackson.databind.JsonNode` and its subclasses (`ArrayNode`, `ObjectNode`, ...) -- `com.arangodb.util.RawJson` -- `com.arangodb.util.RawBytes` -- `com.arangodb.entity.BaseDocument` -- `com.arangodb.entity.BaseEdgeDocument` - -Note that in `arangodb-java-driver-shaded`, due to dependencies relocation, the -fully-qualified class name of first entry above (`JsonNode`) is: -`com.arangodb.shaded.fasterxml.jackson.databind.JsonNode`. -The same relocation rule is also applied to its subclasses (`ArrayNode`, `ObjectNode`, ...). - -The **user-data serde** is used to serialize and deserialize the user-data, -namely the data representing: -- documents -- nodes -- edges -- AQL bind variables -- transactions parameters -- bodies of custom requests and custom responses (`com.arangodb.Request` and `com.arangodb.Response`). - -A `user-data serde` implements the `com.arangodb.serde.ArangoSerde` interface, -which is an abstract API with no dependencies on specific libraries. -The `user-data serde` can be explicitly registered via `ArangoDB.Builder#serde(ArangoSerde)`. -If no serde is registered, then the driver will use SPI (Service Provider Interface) to automatically -discover and load serde service providers (instances of `com.arangodb.serde.ArangoSerdeProvider`). -In case no `user-data serde` is explicitly registered and no serde service provider can be discovered via SPI, then the -**internal serde** will be used to serialize and deserialize user-data. In this case, please note that the -**internal serde** is not part of the public API and could change in future releases without notice, thus breaking -client applications relying on it to serialize or deserialize user-data. - -Examples of custom `user-data serde` implementations can be found here: -- [JSON_B serde](https://github.com/arangodb/arangodb-java-driver/tree/main/jsonb-serde/src/main/java/com/arangodb/serde/jsonb): - a custom serde implementation based on `JSON-B` (supporting `JSON` format only) -- [Micronaut Serialization serde](https://github.com/arangodb-helper/arango-micronaut-native-example/blob/main/src/main/kotlin/com/example/ArangoService.kt): - a custom serde implementation based on - [Micronaut Serialization](https://micronaut-projects.github.io/micronaut-serialization/latest/guide/index.html) - -## JacksonSerde (default user-data serde) - -The default `user-data serde` is `com.arangodb.serde.jackson.JacksonSerde`. -It is implemented delegating [Jackson](https://github.com/FasterXML/jackson) -`ObjectMapper`, thus compatible with Jackson Streaming, Data Binding and Tree Model API. - -It supports both `JSON` and `VPACK` data formats, while offering the same API to the user. - -The `JSON` implementation is provided by the -[`com.arangodb:jackson-serde-json` module](https://github.com/arangodb/arangodb-java-driver/tree/main/jackson-serde-json) -and transitively imported by `arangodb-java-driver`. This implementation is -used by default. - -The `VPACK` implementation is provided by the optional -[`com.arangodb:jackson-serde-vpack` module](https://github.com/arangodb/arangodb-java-driver/tree/main/jackson-serde-vpack), -which uses the [jackson-dataformat-velocypack](https://github.com/arangodb/jackson-dataformat-velocypack) -implementation internally. - -### Mapping API - -`JacksonSerde` is fully compatible with [Jackson Databind](https://github.com/FasterXML/jackson-databind) -API. To customize the serialization and deserialization behavior using the -Jackson Data Binding API, entities can be annotated with -[Jackson Annotations](https://github.com/FasterXML/jackson-annotations). -For more advanced customizations refer to [Custom serializer](#custom-serializers) section. - -### Document Annotations - -The annotations from package `com.arangodb.serde.jackson` can be used to annotate -fields, parameters, getters and setters for mapping values representing ArangoDB -documents metadata (`_id`, `_key`, `_rev`, `_from`, `_to`): -- `@Id` -- `@Key` -- `@Rev` -- `@From` -- `@To` - -### Renaming Properties - -To use a different serialized name for a field, use the annotation `@JsonProperty`. - -```java -public class MyObject { - @JsonProperty("title") - private String name; -} -``` - -### Ignoring properties - -To ignore fields use the annotation `@JsonIgnore`. - -```java -public class Value { - @JsonIgnore - public int internalValue; -} -``` - -### Custom Configuration - -Create an instance of `JacksonSerde`, configure the underlying `ObjectMapper` -and register it in the driver: - -```java -JacksonSerde serde = JacksonSerde.of(ContentType.JSON); -serde.configure((ObjectMapper mapper) -> { - // ... -}); - -ArangoDB adb = new ArangoDB.Builder() - .serde(serde) - // ... - .build(); -``` - -See also [Jackson Databind](https://github.com/FasterXML/jackson-databind/wiki/JacksonFeatures) -configurable features. - -### Custom serializers - -The serialization and deserialization can be customized using the lower level -Streaming API or the Tree Model API, creating and registering respectively -`JsonSerializer` and `JsonDeserializer`, as specified by the Jackson API -for [CustomSerializers](https://github.com/FasterXML/jackson-docs/wiki/JacksonHowToCustomSerializers). - -```java -static class PersonSerializer extends JsonSerializer { - @Override - public void serialize(Person value, JsonGenerator gen, SerializerProvider serializers) throws IOException { - // example using the Streaming API - gen.writeStartObject(); - gen.writeFieldName("name"); - gen.writeString(value.name); - gen.writeEndObject(); - } -} - -static class PersonDeserializer extends JsonDeserializer { - @Override - public Person deserialize(JsonParser parser, DeserializationContext ctxt) throws IOException { - // example using the Tree Model API - Person person = new Person(); - JsonNode rootNode = parser.getCodec().readTree(parser); - JsonNode nameNode = rootNode.get("name"); - if (nameNode != null && nameNode.isTextual()) { - person.name = nameNode.asText(); - } - return person; - } -} - -// registering using annotation -@JsonSerialize(using = PersonSerializer.class) -public static class Person { - public String name; -} - -// registering programmatically -JacksonSerde serde = JacksonSerde.of(ContentType.JSON); -serde.configure(mapper -> { - SimpleModule module = new SimpleModule("PersonModule"); - module.addDeserializer(Person.class, new PersonDeserializer()); - mapper.registerModule(module); -}); - -ArangoDB adb = new ArangoDB.Builder() - .serde(serde) - // ... - .build(); -``` - -### Jackson datatype and language modules - -The `JacksonSerde` can be configured -with [Jackson datatype modules](https://github.com/FasterXML/jackson#third-party-datatype-modules) -as well as [Jackson JVM Language modules](https://github.com/FasterXML/jackson#jvm-language-modules). - -### Kotlin - -[Kotlin language module](https://github.com/FasterXML/jackson-module-kotlin) -enables support for Kotlin classes and types and can be registered in the following way: - -```kotlin -val arangoDB = ArangoDB.Builder() - .serde(JacksonSerde.of(ContentType.JSON).apply { - configure { it.registerModule(KotlinModule()) } - }) - .build() -``` - -### Scala - -[Scala language module](https://github.com/FasterXML/jackson-module-scala) -enables support for Scala classes and types and can be registered in the following way: - -```scala -val serde = JacksonSerde.of(ContentType.JSON) -serde.configure(mapper => mapper.registerModule(DefaultScalaModule)) - -val arangoDB = new ArangoDB.Builder() - .serde(arangoJack) - .build() -``` - -### Java 8 types - -Support for Java 8 features is offered by -[jackson-modules-java8](https://github.com/FasterXML/jackson-modules-java8). - -### Joda types - -Support for Joda data types, such as DateTime, is offered by -[jackson-datatype-joda](https://github.com/FasterXML/jackson-datatype-joda). - -### Metadata fields - -Metadata fields `_id`, `_key`, `_rev`, `_from`, `_to` can be mapped using -respectively the annotations (from package `com.arangodb.serde.jackson`): -`@Id`, `@Key`, `@Rev`, `@From`, `@To`. - -```java -public class MyObject { - - @Key - private String key; - - // ... -} -``` diff --git a/site/content/arangodb/3.13/develop/drivers/javascript.md b/site/content/arangodb/3.13/develop/drivers/javascript.md deleted file mode 100644 index 5161b596b2..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/javascript.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: ArangoDB JavaScript driver -menuTitle: JavaScript driver -weight: 25 -description: >- - arangojs is the JavaScript driver to access ArangoDB from outside the - database system, primarily with Node.js -aliases: - - nodejs # 3.12 -> 3.12 ---- -The official ArangoDB low-level JavaScript client. - -- Repository: -- Reference: -- [Changelog](https://github.com/arangodb/arangojs/blob/main/CHANGELOG.md) - -{{< info >}} -If you are looking for the ArangoDB JavaScript API in -[Foxx](https://www.arangodb.com/community-server/foxx/) or the `arangosh` -interactive shell, please refer to the documentation about the -[`@arangodb` module](../javascript-api/@arangodb/_index.md) instead. - -The JavaScript driver is **only** meant to be used when accessing ArangoDB from -**outside** the database. -{{< /info >}} - -## Compatibility - -The arangojs driver is compatible with the latest stable version of ArangoDB -available at the time of the driver release and remains compatible with the two -most recent Node.js LTS versions in accordance with the official -[Node.js long-term support schedule](https://github.com/nodejs/LTS). -Versions of ArangoDB that have reached their [end of life](https://arangodb.com/subscriptions/end-of-life-notice/) -by the time of a driver release are explicitly not supported. - -The [_arangoVersion_ option](https://arangodb.github.io/arangojs/latest/types/configuration.ConfigOptions.html) -can be used to tell arangojs to target a specific -ArangoDB version. Depending on the version this will enable or disable certain -methods and change behavior to maintain compatibility with the given version. -The oldest version of ArangoDB supported by arangojs when using this option -is 2.8.0 (using `arangoVersion: 20800`). - -## Versions - -The version number of this driver does not indicate supported ArangoDB versions! - -This driver uses semantic versioning: - -- A change in the bugfix version (e.g. X.Y.0 -> X.Y.1) indicates internal - changes and should always be safe to upgrade. -- A change in the minor version (e.g. X.1.Z -> X.2.0) indicates additions and - backwards-compatible changes that should not affect your code. -- A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_ - changes that require changes in your code to upgrade. - -If you are getting weird errors or functions seem to be missing, make sure you -are using the latest version of the driver and following documentation written -for a compatible version. If you are following a tutorial written for an older -version of arangojs, you can install that version using the `@` -syntax: - -```sh -# for version 9.x.x -yarn add arangojs@9 -# - or - -npm install --save arangojs@9 -``` - -You can find the documentation for each version by clicking on the corresponding -date on the left in -[the list of version tags](https://github.com/arangodb/arangojs/tags). - -## Install - -{{< tabs "js-install" >}} - -{{< tab "Yarn" >}} -```sh -yarn add arangojs -``` -{{< /tab >}} - -{{< tab "NPM" >}} -```sh -npm install --save arangojs -``` -{{< /tab >}} - -{{< tab "From source" >}} -```bash -git clone https://github.com/arangodb/arangojs.git -cd arangojs -npm install -npm run build -``` - -Building natively on Windows is not supported but you can use a virtual Linux -or Linux container. -{{< /tab >}} - -{{< tab "For browsers" >}} -When using modern JavaScript tooling with a bundler and compiler (e.g. Babel), -arangojs can be installed using NPM or Yarn like any other dependency. - -You can also use [jsDelivr CDN](https://www.jsdelivr.com/) during development: - -```js - - -``` -{{< /tab >}} - -{{< /tabs >}} - -## Basic usage example - -Modern JavaScript/TypeScript with async/await and ES Modules: - -```js -import { Database, aql } from "arangojs"; - -const db = new Database(); -const Pokemons = db.collection("my-pokemons"); - -async function main() { - try { - const pokemons = await db.query(aql` - FOR pokemon IN ${Pokemons} - FILTER pokemon.type == "fire" - RETURN pokemon - `); - console.log("My pokemans, let me show you them:"); - for await (const pokemon of pokemons) { - console.log(pokemon.name); - } - } catch (err) { - console.error(err.message); - } -} - -main(); -``` - -Using a different database: - -```js -const db = new Database({ - url: "http://127.0.0.1:8529", - databaseName: "pancakes", - auth: { username: "root", password: "hunter2" }, -}); - -// The credentials can be swapped at any time -db.useBasicAuth("admin", "maplesyrup"); -``` - -Old-school JavaScript with promises and CommonJS: - -```js -var arangojs = require("arangojs"); -var Database = arangojs.Database; - -var db = new Database(); -var pokemons = db.collection("pokemons"); - -db.query({ - query: "FOR p IN @@c FILTER p.type == 'fire' RETURN p", - bindVars: { "@c": "pokemons" }, -}) - .then(function (cursor) { - console.log("My pokemons, let me show you them:"); - return cursor.forEach(function (pokemon) { - console.log(pokemon.name); - }); - }) - .catch(function (err) { - console.error(err.message); - }); -``` - -For AQL, please check out the -[aql template tag](https://arangodb.github.io/arangojs/latest/functions/aql.aql.html) -for writing parametrized AQL queries without making your code vulnerable to -injection attacks. - -## Error responses - -If the server returns an ArangoDB error response, arangojs throws an `ArangoError` -with an `errorNum` property indicating the -[ArangoDB error code](../error-codes.md) and expose the response body -as the response property of the error object. - -For all other errors during the request/response cycle arangojs throws a -`NetworkError` or a more specific subclass thereof and expose the originating -request object as the `request` property of the error object. - -If the server responded with a non-2xx status code, this `NetworkError` is an -`HttpError` with a code property indicating the HTTP status code of the response -and a response property containing the `response` object itself. - -If the error is caused by an exception, the originating exception is available -as the `cause` property of the error object thrown by arangojs. -For network errors, this is often a `TypeError`. - -**Example** - -```js -try { - const info = await db.createDatabase("mydb"); - // database created -} catch (err) { - console.error(err.stack); -} -``` diff --git a/site/content/arangodb/3.13/develop/drivers/python.md b/site/content/arangodb/3.13/develop/drivers/python.md deleted file mode 100644 index 4b028a616c..0000000000 --- a/site/content/arangodb/3.13/develop/drivers/python.md +++ /dev/null @@ -1,678 +0,0 @@ ---- -title: ArangoDB Python driver -menuTitle: Python driver -weight: 30 -description: >- - Python-Arango is the official ArangoDB driver that provides Python - applications with the complete range of features exposed by the server API ---- -The Python-Arango driver is the recommended driver for using ArangoDB as the -database backend from Python. It is maintained by ArangoDB and the community. - -- Repository: -- Reference: -- [Tutorial](https://university.arangodb.com/courses/python-driver-tutorial/) -- [Releases](https://github.com/arangodb/python-arango/releases) - -There is also an asyncio counterpart called `python-arango-async`. -It has a similar API and features type wrappers. - -- Repository: -- Reference: -- [Tutorial](https://github.com/arangodb/python-arango-async/wiki/Tutorial) -- [Releases](https://github.com/arangodb/python-arango-async/releases) - -## Installation - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -The `python-arango` library can be used in any Python project that targets -Python version 3.8 or later. - -To install the library using PIP, run the following command in a terminal: - -```sh -pip install python-arango --upgrade -``` - -You can then import the library in your project as follows: - -```python -from arango import ArangoClient -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -The `python-arango-async` library can be used in any Python project that targets -Python version 3.10 or later. - -To install the library using PIP, run the following command in a terminal: - -```sh -pip install python-arango-async --upgrade -``` - -You can then import the library in your project as follows: - -```python -from arangoasync import ArangoClient -``` -{{< /tab >}} - -{{< /tabs >}} - - - -## Get started - -The following example shows how to use the driver from connecting to ArangoDB, -over creating databases, collections, indexes, and documents, to retrieving -data using queries: - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -from arango import ArangoClient - -# Initialize the client for ArangoDB. -client = ArangoClient(hosts="http://localhost:8529") - -# Connect to "_system" database as root user. -sys_db = client.db("_system", username="root", password="passwd") - -# Create a new database named "test". -sys_db.create_database("test") - -# Connect to "test" database as root user. -db = client.db("test", username="root", password="passwd") - -# Create a new collection named "students". -students = db.create_collection("students") - -# Add a persistent index to the collection. -students.add_index({'type': 'persistent', 'fields': ['name'], 'unique': True}) - -# Insert new documents into the collection. -students.insert({"name": "jane", "age": 39}) -students.insert({"name": "josh", "age": 18}) -students.insert({"name": "judy", "age": 21}) - -# Execute an AQL query and iterate through the result cursor. -cursor = db.aql.execute("FOR doc IN students RETURN doc") -student_names = [document["name"] for document in cursor] -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python -from arangoasync import ArangoClient -from arangoasync.auth import Auth - -# Initialize the client for ArangoDB. -async with ArangoClient(hosts="http://localhost:8529") as client: - auth = Auth(username="root", password="passwd") - - # Connect to "_system" database as root user. - sys_db = await client.db("_system", auth=auth) - - # Create a new database named "test". - await sys_db.create_database("test") - - # Connect to "test" database as root user. - db = await client.db("test", auth=auth) - - # Create a new collection named "students". - students = await db.create_collection("students") - - # Add a persistent index to the collection. - await students.add_index(type="persistent", fields=["name"], options={"unique": True}) - - # Insert new documents into the collection. - await students.insert({"name": "jane", "age": 39}) - await students.insert({"name": "josh", "age": 18}) - await students.insert({"name": "judy", "age": 21}) - - # Execute an AQL query and iterate through the result cursor. - cursor = await db.aql.execute("FOR doc IN students RETURN doc") - async with cursor: - student_names = [] - async for doc in cursor: - student_names.append(doc["name"]) -``` - -You may also use the client without a context manager, but you must ensure to -close the client when done. - -```python -from arangoasync import ArangoClient -from arangoasync.auth import Auth - -client = ArangoClient(hosts="http://localhost:8529") -auth = Auth(username="root", password="passwd") -sys_db = await client.db("_system", auth=auth) - -# Create a new database named "test". -await sys_db.create_database("test") - -# Connect to "test" database as root user. -db = await client.db("test", auth=auth) - -# List all collections in the "test" database. -collections = await db.collections() - -# Close the client when done. -await client.close() -``` -{{< /tab >}} - -{{< /tabs >}} - -The following example shows how to create a [named graph](../../graphs/_index.md), -populate it with nodes and edges, and query it with a graph traversal: - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -from arango import ArangoClient - -# Initialize the client for ArangoDB. -client = ArangoClient(hosts="http://localhost:8529") - -# Connect to "test" database as root user. -db = client.db("test", username="root", password="passwd") - -# Create a new graph named "school". -graph = db.create_graph("school") - -# Create a new EnterpriseGraph -eegraph = db.create_graph( - name="school", - smart=True) - -# Create node collections for the graph. -students = graph.create_vertex_collection("students") -lectures = graph.create_vertex_collection("lectures") - -# Create an edge definition (relation) for the graph. -edges = graph.create_edge_definition( - edge_collection="register", - from_vertex_collections=["students"], - to_vertex_collections=["lectures"] -) - -# Insert node documents into "students" (from) node collection. -students.insert({"_key": "01", "full_name": "Anna Smith"}) -students.insert({"_key": "02", "full_name": "Jake Clark"}) -students.insert({"_key": "03", "full_name": "Lisa Jones"}) - -# Insert node documents into "lectures" (to) node collection. -lectures.insert({"_key": "MAT101", "title": "Calculus"}) -lectures.insert({"_key": "STA101", "title": "Statistics"}) -lectures.insert({"_key": "CSC101", "title": "Algorithms"}) - -# Insert edge documents into "register" edge collection. -edges.insert({"_from": "students/01", "_to": "lectures/MAT101"}) -edges.insert({"_from": "students/01", "_to": "lectures/STA101"}) -edges.insert({"_from": "students/01", "_to": "lectures/CSC101"}) -edges.insert({"_from": "students/02", "_to": "lectures/MAT101"}) -edges.insert({"_from": "students/02", "_to": "lectures/STA101"}) -edges.insert({"_from": "students/03", "_to": "lectures/CSC101"}) - -# Traverse the graph in outbound direction, breath-first. -query = """ - FOR v, e, p IN 1..3 OUTBOUND 'students/01' GRAPH 'school' - OPTIONS { bfs: true, uniqueVertices: 'global' } - RETURN {node: v, edge: e, path: p} - """ -cursor = db.aql.execute(query) -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python -from arangoasync import ArangoClient -from arangoasync.auth import Auth - -# Initialize the client for ArangoDB. -async with ArangoClient(hosts="http://localhost:8529") as client: - auth = Auth(username="root", password="passwd") - - # Connect to "test" database as root user. - db = await client.db("test", auth=auth) - - # Get the API wrapper for graph "school". - if await db.has_graph("school"): - graph = db.graph("school") - else: - graph = await db.create_graph("school") - - # Create vertex collections for the graph. - students = await graph.create_vertex_collection("students") - lectures = await graph.create_vertex_collection("lectures") - - # Create an edge definition (relation) for the graph. - edges = await graph.create_edge_definition( - edge_collection="register", - from_vertex_collections=["students"], - to_vertex_collections=["lectures"] - ) - - # Insert vertex documents into "students" (from) vertex collection. - await students.insert({"_key": "01", "full_name": "Anna Smith"}) - await students.insert({"_key": "02", "full_name": "Jake Clark"}) - await students.insert({"_key": "03", "full_name": "Lisa Jones"}) - - # Insert vertex documents into "lectures" (to) vertex collection. - await lectures.insert({"_key": "MAT101", "title": "Calculus"}) - await lectures.insert({"_key": "STA101", "title": "Statistics"}) - await lectures.insert({"_key": "CSC101", "title": "Algorithms"}) - - # Insert edge documents into "register" edge collection. - await edges.insert({"_from": "students/01", "_to": "lectures/MAT101"}) - await edges.insert({"_from": "students/01", "_to": "lectures/STA101"}) - await edges.insert({"_from": "students/01", "_to": "lectures/CSC101"}) - await edges.insert({"_from": "students/02", "_to": "lectures/MAT101"}) - await edges.insert({"_from": "students/02", "_to": "lectures/STA101"}) - await edges.insert({"_from": "students/03", "_to": "lectures/CSC101"}) - - # Traverse the graph in outbound direction, breath-first. - query = """ - FOR v, e, p IN 1..3 OUTBOUND 'students/01' GRAPH 'school' - OPTIONS { bfs: true, uniqueVertices: 'global' } - RETURN {vertex: v, edge: e, path: p} - """ - - async with await db.aql.execute(query) as cursor: - async for doc in cursor: - print(doc) -``` -{{< /tab >}} - -{{< /tabs >}} - -## Work with databases - -### Connect to a database - -To connect to a database, create an instance of `ArangoClient` which provides a -connection to the database server. Then call its `db` method and pass the -database name, user name, and password as parameters. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -from arango import ArangoClient - -# Initialize a client -client = ArangoClient(hosts="http://localhost:8529") - -# Connect to the system database -sys_db = client.db("_system", username="root", password="passwd") -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python -from arangoasync import ArangoClient -from arangoasync.auth import Auth - -# Initialize the client for ArangoDB. -async with ArangoClient(hosts="http://localhost:8529") as client: - auth = Auth(username="root", password="passwd") - - # Connect to "_system" database as root user. - sys_db = await client.db("_system", auth=auth) -``` -{{< /tab >}} - -{{< /tabs >}} - -### Retrieve a list of all databases - -To retrieve a list of all databases on an ArangoDB server, connect to the -`_system` database and call the `databases()` method. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Retrieve the names of all databases on the server as list of strings -db_list = sys_db.databases() -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Retrieve the names of all databases on the server as list of strings - db_list = await sys_db.databases() -``` -{{< /tab >}} - -{{< /tabs >}} - -### Create a database - -To create a new database, connect to the `_system` database and call -`create_database()`. - - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Create a new database named "test". -ok = sys_db.create_database("test") - -# Connect to "test" database as root user. -test_db = client.db("test", username="root", password="passwd") -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Create a new database named "test". - ok = await sys_db.create_database("test") - - # Connect to "test" database as root user. - test_db = await client.db("test", auth=auth) -``` -{{< /tab >}} - -{{< /tabs >}} - -### Delete a database - -To delete an existing database, connect to the `_system` database and call -`delete_database()` passing the name of the database to be deleted as a -parameter. The `_system` database cannot be deleted. Make sure to specify -the correct database name when you are deleting databases. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Delete the 'test' database -sys_db.delete_database("test") -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Delete the 'test' database - ok = await sys_db.delete_database("test") -``` -{{< /tab >}} - -{{< /tabs >}} - -## Work with collections - -### Retrieve a list of collections - -To retrieve a list of collections in a database, connect to the database and -call `collections()`. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Connect to the database -db = client.db(db_name, username=user_name, password=pass_word) - -# Retrieve the list of collections -collection_list = db.collections() -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Connect to the database - db = await client.db(db_name, auth=Auth(username=user_name, password=pass_word)) - - # Retrieve the list of collections as CollectionInfo objects - collection_list = await db.collections() -``` -{{< /tab >}} - -{{< /tabs >}} - -### Create a collection - -To create a new collection, connect to the database and call `create_collection()`. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Create a new collection for doctors -doctors_col = db.create_collection(name="doctors") - -# Create another new collection for patients -patients_col = db.create_collection(name="patients") -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Create a new collection for doctors - doctors_col = await db.create_collection(name="doctors") - - # Create another new collection for patients - patients_col = await db.create_collection(name="patients") -``` -{{< /tab >}} - -{{< /tabs >}} - -### Delete a collection - -To delete a collection, connect to the database and call `delete_collection()`, -passing the name of the collection to be deleted as a parameter. Make sure to -specify the correct collection name when you delete collections. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Delete the 'doctors' collection -db.delete_collection(name="doctors") -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Delete the 'doctors' collection - ok = await db.delete_collection(name="doctors") -``` -{{< /tab >}} - -{{< /tabs >}} - -## Work with documents - -### Create a document - -To create a new document, get a reference to the collection and call its -`insert()` method, passing the object/document to be created in ArangoDB as -a parameter. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Get a reference to the 'patients' collection -patients_col = db.collection(name="patients") - -# Insert two new documents into the 'patients' collection -meta1 = patients_col.insert({"name": "Jane", "age": 39}) -meta2 = patients_col.insert({"name": "John", "age": 18}) -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Get a reference to the 'patients' collection - patients_col = db.collection(name="patients") - - # Insert two new documents into the 'patients' collection - meta1 = await patients_col.insert({"name": "Jane", "age": 39}) - meta2 = await patients_col.insert({"name": "John", "age": 18}) -``` -{{< /tab >}} - -{{< /tabs >}} - -In this example, John's patient record is as follows: - -```json -{ - "_id": "patients/741603", - "_rev": "_fQ2grGu---", - "_key": "741603", - "name": "John", - "age": 18 -} -``` - -### Update a document - -To patch or partially update a document, call the `update()` method of the -collection and pass the object/document as a parameter. The document must have -a property named `_key` holding the unique key assigned to the document. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Patch John's patient record by adding a city property to the document -meta = patients_col.update({ "_key": "741603", "city": "Cleveland" }) -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Patch John's patient record by adding a city property to the document - meta = await patients_col.update({ "_key": "741603", "city": "Cleveland" }) -``` -{{< /tab >}} - -{{< /tabs >}} - -After the patching operation, John's document is as follows for example: - -```json -{ - "_id": "patients/741603", - "_rev": "_fQ2h4TK---", - "_key": "741603", - "name": "John", - "age": 18, - "city": "Cleveland" -} -``` - -Notice that the record was patched by adding a `city` property to the document. -All other properties remain the same. - -### Replace a document - -To replace or fully update a document, call the `replace()` method of the -collection and pass the object/document that fully replaces thee existing -document as a parameter. The document must have a property named `_key` holding -the unique key assigned to the document. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Replace John's document -meta = patients_col.replace({ "_key": "741603", "fullname": "John Doe", "age": 18, "city": "Cleveland" }) -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Replace John's document - meta = await patients_col.replace({ "_key": "741603", "fullname": "John Doe", "age": 18, "city": "Cleveland" }) -``` -{{< /tab >}} - -{{< /tabs >}} - -After the replacement operation, John's document is as follows: - -```json -{ - "_id": "patients/741603", - "_rev": "_fQ2uY3y---", - "_key":"741603", - "fullname": "John Doe", - "age": 18, - "city": "Cleveland" -} -``` - -Notice that the `name` property is now gone from John's document because it was -not specified in the request when the document was fully replaced. - -### Delete a document - -To delete a document, call the `delete()` method of the collection and pass an -document containing at least the `_key` attribute as a parameter. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Delete John's document -patients_col.delete({ "_key": "741603" }) -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Delete John's document - meta = await patients_col.delete({ "_key": "741603" }) -``` -{{< /tab >}} - -{{< /tabs >}} - -## Work with AQL - -### Run AQL queries - -To run a query, connect to the desired database and call `aql.execute()`. -This returns a cursor, which lets you fetch the results in batches. You can -iterate over the cursor to automatically fetch the data. - -{{< tabs "python-driver" >}} - -{{< tab "python-arango" >}} -```python -# Run a query -cursor = db.aql.execute('FOR i IN 1..@value RETURN i', bind_vars={'value': 3}) - -# Print the results -for doc in cursor: - print(doc) -``` -{{< /tab >}} - -{{< tab "python-arango-async" >}} -```python - # Run a query - cursor = await db.aql.execute('FOR i IN 1..@value RETURN i', bind_vars={'value': 3}) - - # Print the results - async with cursor: - async for doc in cursor: - print(doc) -``` -{{< /tab >}} - -{{< /tabs >}} diff --git a/site/content/arangodb/3.13/develop/http-api/_index.md b/site/content/arangodb/3.13/develop/http-api/_index.md index e42c7b49f3..e52e55ee54 100644 --- a/site/content/arangodb/3.13/develop/http-api/_index.md +++ b/site/content/arangodb/3.13/develop/http-api/_index.md @@ -13,7 +13,7 @@ world wide web. All interactions with a server are ultimately carried out via this HTTP API. You can use the API by sending HTTP requests to the server directly, but the -more common way of communicating with the server is via a [database driver](../drivers/_index.md). +more common way of communicating with the server is via a [database driver](../../../../ecosystem/drivers/_index.md). A driver abstracts the complexity of the API away by providing a simple interface for your programming language or environment and handling things like authentication, connection pooling, asynchronous requests, and multi-part replies diff --git a/site/content/arangodb/3.13/develop/integrations/_index.md b/site/content/arangodb/3.13/develop/integrations/_index.md deleted file mode 100644 index 3469808d73..0000000000 --- a/site/content/arangodb/3.13/develop/integrations/_index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Integrations -menuTitle: Integrations -weight: 290 -description: >- - Integrations for third-party tools and frameworks let you use ArangoDB as the - database backend for these products ---- -Database integrations allow applications to work with different database systems -using a common interface. They are higher-level than database drivers because -they abstract away the details of specific database systems, especially the -low-level network communication. - -## Spring Data - -The [**Spring Data integration**](spring-data-arangodb/_index.md) for ArangoDB -lets you use ArangoDB as a database system in Spring-based Java applications. - -- [Tutorial](spring-data-arangodb/_index.md#get-started) -- Repository: [github.com/arangodb/spring-data](https://github.com/arangodb/spring-data) -- [Changelog](https://github.com/arangodb/spring-data/blob/main/ChangeLog.md) - -## Spring Boot Starter - -The [**Spring Boot Starter**](spring-boot-arangodb.md) simplifies the use of the -Spring Data integration for ArangoDB so you get started quickly. It is a set of -convenient dependency descriptors that you can include in your application. - -- [Tutorial](spring-boot-arangodb.md#get-started) -- Repository: -- [Changelog](https://github.com/arangodb/spring-boot-starter/blob/main/Changelog.md) - -## Apache Spark - -The [**ArangoDB Datasource for Apache Spark**](arangodb-datasource-for-apache-spark.md) is a -library that lets you use Apache Spark with ArangoDB for data processing. -Apache Spark has first-party support for the Scala, Java, Python, and R language. - -- Repository: [github.com/arangodb/arangodb-spark-datasource](https://github.com/arangodb/arangodb-spark-datasource) -- [Changelog](https://github.com/arangodb/arangodb-spark-datasource/blob/main/ChangeLog.md) - -## Apache Kafka - -The [**Kafka Connect ArangoDB Sink Connector**](kafka-connect-arangodb-sink-connector/_index.md) -allows you to export data from Apache Kafka to ArangoDB. - -- Repository: [github.com/arangodb/kafka-connect-arangodb/](https://github.com/arangodb/kafka-connect-arangodb/) -- [Demo](https://github.com/arangodb/kafka-connect-arangodb/tree/main/demo) -- [Changelog](https://github.com/arangodb/kafka-connect-arangodb/blob/main/ChangeLog.md) - -## TinkerPop Provider - -The [**ArangoDB TinkerPop Provider**](arangodb-tinkerpop-provider.md) is an implementation of -the [Apache TinkerPop OLTP Provider](https://tinkerpop.apache.org/docs/3.7.3/dev/provider) API -for ArangoDB. - -- Repository: [github.com/arangodb/arangodb-tinkerpop-provider](https://github.com/arangodb/arangodb-tinkerpop-provider) -- [Changelog](https://github.com/arangodb/arangodb-tinkerpop-provider/blob/main/CHANGELOG.md) diff --git a/site/content/arangodb/3.13/develop/integrations/arangodb-datasource-for-apache-spark.md b/site/content/arangodb/3.13/develop/integrations/arangodb-datasource-for-apache-spark.md deleted file mode 100644 index aeaf9d379d..0000000000 --- a/site/content/arangodb/3.13/develop/integrations/arangodb-datasource-for-apache-spark.md +++ /dev/null @@ -1,422 +0,0 @@ ---- -title: ArangoDB Datasource for Apache Spark -menuTitle: Datasource for Apache Spark -weight: 10 -description: >- - ArangoDB Datasource for Apache Spark allows batch reading and writing Spark DataFrame data -aliases: -- arangodb-spark-connector -- arangodb-spark-connector/getting-started -- arangodb-spark-connector/reference -- arangodb-spark-connector/reference/java -- arangodb-spark-connector/reference/scala ---- -ArangoDB Datasource for Apache Spark allows batch reading and writing Spark DataFrame data from and to ArangoDB, by implementing the Spark Data Source V2 API. - -Reading tasks are parallelized according to the number of shards of the related ArangoDB collection, and the writing ones - depending on the source DataFrame partitions. The network traffic is load balanced across the available DB Coordinators. - -Filter predicates and column selections are pushed down to the DB by dynamically generating AQL queries, which will fetch only the strictly required data, thus saving network and computational resources both on the Spark and the DB side. - -The connector is usable from all the Spark supported client languages: Scala, Python, Java, and R. - -This library works with all the non-EOLed [ArangoDB versions](https://www.arangodb.com/subscriptions/end-of-life-notice/). - -## Supported versions - -There are several variants of this library, each one compatible with different Spark and Scala versions: - -- `com.arangodb:arangodb-spark-datasource-3.3_2.12` (Spark 3.3, Scala 2.12) -- `com.arangodb:arangodb-spark-datasource-3.3_2.13` (Spark 3.3, Scala 2.13) -- `com.arangodb:arangodb-spark-datasource-3.4_2.12` (Spark 3.4, Scala 2.12) (compatible with Spark `3.4.2+`) -- `com.arangodb:arangodb-spark-datasource-3.4_2.13` (Spark 3.4, Scala 2.13) (compatible with Spark `3.4.2+`) -- `com.arangodb:arangodb-spark-datasource-3.5_2.12` (Spark 3.5, Scala 2.12) -- `com.arangodb:arangodb-spark-datasource-3.5_2.13` (Spark 3.5, Scala 2.13) - -The following variants are no longer supported: - -- `com.arangodb:arangodb-spark-datasource-2.4_2.11` (Spark 2.4, Scala 2.11) -- `com.arangodb:arangodb-spark-datasource-2.4_2.12` (Spark 2.4, Scala 2.12) -- `com.arangodb:arangodb-spark-datasource-3.1_2.12` (Spark 3.1, Scala 2.12) -- `com.arangodb:arangodb-spark-datasource-3.2_2.12` (Spark 3.2, Scala 2.12) -- `com.arangodb:arangodb-spark-datasource-3.2_2.13` (Spark 3.2, Scala 2.13) - -Since version `1.7.0`, due to [breaking changes](https://github.com/apache/spark/commit/ad29290a02fb94a958fd21e301100338c9f5b82a#diff-b25c8acff88c1b4850c6642e80845aac4fb882c664795c3b0aa058e37ed732a0L42-R52) -in Spark `3.4.2`, `arangodb-spark-datasource-3.4` is not compatible anymore with Spark versions `3.4.0` and `3.4.1`. - -In the following sections the `${sparkVersion}` and `${scalaVersion}` placeholders refer to the Spark and Scala versions. - -## Setup - -To import ArangoDB Datasource for Apache Spark in a Maven project: - -```xml - - - com.arangodb - arangodb-spark-datasource-${sparkVersion}_${scalaVersion} - x.y.z - - -``` - -Substitute `x.y.z` with the latest available version that is compatible. - -To use in an external Spark cluster, submit your application with the following parameter: - -```sh ---packages="com.arangodb:arangodb-spark-datasource-${sparkVersion}_${scalaVersion}:x.y.z" -``` - -## General Configuration - -- `user`: db user, `root` by default -- `password`: db password -- `endpoints`: list of Coordinators, e.g. `c1:8529,c2:8529` (required) -- `acquireHostList`: acquire the list of all known hosts in the cluster (`true` or `false`), `false` by default -- `protocol`: communication protocol (`vst`, `http`, or `http2`), `http2` by default -- `contentType`: content type for driver communication (`json` or `vpack`), `json` by default -- `timeout`: driver connect and request timeout in ms, `300000` by default -- `ssl.enabled`: ssl secured driver connection (`true` or `false`), `false` by default -- `ssl.verifyHost`: whether TLS hostname verification is enabled, `true` by default -- `ssl.cert.value`: Base64 encoded certificate -- `ssl.cert.type`: certificate type, `X.509` by default -- `ssl.cert.alias`: certificate alias name, `arangodb` by default -- `ssl.algorithm`: trust manager algorithm, `SunX509` by default -- `ssl.keystore.type`: keystore type, `jks` by default -- `ssl.protocol`: SSLContext protocol, `TLS` by default -- `ssl.trustStore.path`: trust store path -- `ssl.trustStore.password`: trust store password - -### SSL - -To use TLS-secured connections to ArangoDB, set `ssl.enabled` to `true` and -configure the certificate to use. This can be achieved in one of the following ways: - -- Provide the Base64-encoded certificate as the `ssl.cert.value` configuration entry: - - ```scala - val spark: SparkSession = SparkSession.builder() - // ... - .config("ssl.enabled", "true") - .config("ssl.cert.value", "") - .getOrCreate() - ``` - -- Set the trust store to use in the `ssl.trustStore.path` configuration entry and - optionally set `ssl.trustStore.password`: - - ```scala - val spark: SparkSession = SparkSession.builder() - // ... - .config("ssl.enabled", "true") - .config("ssl.trustStore.path", "") - .config("ssl.trustStore.password", "") - .getOrCreate() - ``` - -- Start the Spark driver and workers with a properly configured trust store: - - ```scala - val spark: SparkSession = SparkSession.builder() - // ... - .config("ssl.enabled", "true") - .getOrCreate() - ``` - - Set the following in the Spark configuration file: - - ```properties - spark.executor.extraJavaOptions=-Djavax.net.ssl.trustStore= -Djavax.net.ssl.trustStorePassword= - spark.driver.extraJavaOptions=-Djavax.net.ssl.trustStore= -Djavax.net.ssl.trustStorePassword= - ``` - - Alternatively, you can set this in the command-line when submitting the Spark job: - - ```sh - ./bin/spark-submit \ - --conf "spark.driver.extraJavaOptions=-Djavax.net.ssl.trustStore= -Djavax.net.ssl.trustStorePassword=" \ - --conf "spark.executor.extraJavaOptions=-Djavax.net.ssl.trustStore= -Djavax.net.ssl.trustStorePassword=" \ - ... - ``` - -### Supported deployment topologies - -The connector can work with a single server and cluster deployments of ArangoDB. - -## Batch Read - -The connector implements support for batch reading from an ArangoDB collection. - -```scala -val df: DataFrame = spark.read - .format("com.arangodb.spark") - .options(options) // Map[String, String] - .schema(schema) // StructType - .load() -``` - -The connector can read data from: -- a collection -- an AQL cursor (query specified by the user) - -When reading data from a **collection**, the reading job is split into many Spark tasks, one for each shard in the ArangoDB source collection. The resulting Spark DataFrame has the same number of partitions as the number of shards in the ArangoDB collection, each one containing data from the respective collection shard. The reading tasks consist of AQL queries that are load balanced across all the available ArangoDB Coordinators. Each query is related to only one shard, therefore it will be executed locally in the DB-Server holding the related shard. - -When reading data from an **AQL cursor**, the reading job cannot be partitioned or parallelized, so it will be less scalable. This mode can be used for reading data coming from different tables, i.e. resulting from an AQL traversal query. - -**Example** - -```scala -val spark: SparkSession = SparkSession.builder() - .appName("ArangoDBSparkDemo") - .master("local[*]") - .config("spark.driver.host", "127.0.0.1") - .getOrCreate() - -val df: DataFrame = spark.read - .format("com.arangodb.spark") - .options(Map( - "password" -> "test", - "endpoints" -> "c1:8529,c2:8529,c3:8529", - "table" -> "users" - )) - .schema(new StructType( - Array( - StructField("likes", ArrayType(StringType, containsNull = false)), - StructField("birthday", DateType, nullable = true), - StructField("gender", StringType, nullable = false), - StructField("name", StructType( - Array( - StructField("first", StringType, nullable = true), - StructField("last", StringType, nullable = false) - ) - ), nullable = true) - ) - )) - .load() - -usersDF.filter(col("birthday") === "1982-12-15").show() -``` - -### Read Configuration - -- `database`: database name, `_system` by default -- `table`: datasource ArangoDB collection name, ignored if `query` is specified. Either `table` or `query` is required. -- `query`: custom AQL read query. If set, `table` will be ignored. Either `table` or `query` is required. -- `batchSize`: reading batch size, `10000` by default -- `sampleSize`: sample size prefetched for schema inference, only used if read schema is not provided, `1000` by default -- `fillBlockCache`: specifies whether the query should store the data it reads in the RocksDB block cache (`true` or `false`), `false` by default -- `stream`: specifies whether the query should be executed lazily, `true` by default -- `ttl`: cursor time to live in seconds, `30` by default -- `mode`: allows setting a mode for dealing with corrupt records during parsing: - - `PERMISSIVE` : win case of a corrupted record, the malformed string is put into a field configured by - `columnNameOfCorruptRecord`, and sets malformed fields to null. To keep corrupt records, a user can set a string - type field named `columnNameOfCorruptRecord` in a user-defined schema. If a schema does not have the field, it drops - corrupt records during parsing. When inferring a schema, it implicitly adds the `columnNameOfCorruptRecord` field in - an output schema - - `DROPMALFORMED`: ignores the whole corrupted records - - `FAILFAST`: throws an exception in case of corrupted records -- `columnNameOfCorruptRecord`: allows renaming the new field having malformed string created by the `PERMISSIVE` mode - -### Predicate and Projection Pushdown - -The connector can convert some Spark SQL filter predicates into AQL predicates and push their execution down to the data source. In this way, ArangoDB can apply the filters and return only the matching documents. - -The following filter predicates (implementations of `org.apache.spark.sql.sources.Filter`) are pushed down: -- `And` -- `Or` -- `Not` -- `EqualTo` -- `EqualNullSafe` -- `IsNull` -- `IsNotNull` -- `GreaterThan` -- `GreaterThanOrEqualFilter` -- `LessThan` -- `LessThanOrEqualFilter` -- `StringStartsWithFilter` -- `StringEndsWithFilter` -- `StringContainsFilter` -- `InFilter` - -Furthermore, the connector will push down the subset of columns required by the Spark query, so that only the relevant documents fields will be returned. - -Predicate and projection pushdowns are only performed while reading an ArangoDB collection (set by the `table` configuration parameter). In case of a batch read from a custom query (set by the `query` configuration parameter), no pushdown optimizations are performed. - -### Read Resiliency - -The data of each partition is read using an AQL cursor. If any error occurs, the read task of the related partition will fail. Depending on the Spark configuration, the task could be retried. - -## Batch Write - -The connector implements support for batch writing to ArangoDB collection. - -```scala -import org.apache.spark.sql.DataFrame - -val df: DataFrame = //... -df.write - .format("com.arangodb.spark") - .mode(SaveMode.Append) - .options(Map( - "password" -> "test", - "endpoints" -> "c1:8529,c2:8529,c3:8529", - "table" -> "users" - )) - .save() -``` - -Write tasks are load balanced across the available ArangoDB Coordinators. The data saved into the ArangoDB is sharded according to the related target collection definition and is different from the Spark DataFrame partitioning. - -### SaveMode - -On writing, `org.apache.spark.sql.SaveMode` is used to specify the expected behavior in case the target collection already exists. - -The following save modes are supported: -- `Append`: the target collection is created, if it does not exist. -- `Overwrite`: the target collection is created, if it does not exist, otherwise it is truncated. Use it in combination with the - `confirmTruncate` write configuration parameter. - -Save modes `ErrorIfExists` and `Ignore` behave the same as `Append`. - -Use the `overwriteMode` write configuration parameter to specify the document overwrite behavior (if a document with the same `_key` already exists). - -### Write Configuration - -- `database`: database name, `_system` by default -- `table`: target ArangoDB collection name (required) -- `batchSize`: writing batch size, `10000` by default -- `byteBatchSize`: byte batch size threshold, only considered for `contentType=json`, `8388608` by default (8 MB) -- `table.shards`: number of shards of the created collection (in case of the `Append` or `Overwrite` SaveMode) -- `table.type`: type (`document` or `edge`) of the created collection (in case of the `Append` or `Overwrite` SaveMode), `document` by default -- `waitForSync`: specifies whether to wait until the documents have been synced to disk (`true` or `false`), `false` by default -- `confirmTruncate`: confirms to truncate table when using the `Overwrite` SaveMode, `false` by default -- `overwriteMode`: configures the behavior in case a document with the specified `_key` value already exists. It is only considered for `Append` SaveMode. - - `ignore` (default for SaveMode other than `Append`): it will not be written - - `replace`: it will be overwritten with the specified document value - - `update`: it will be patched (partially updated) with the specified document value. The overwrite mode can be - further controlled via the `keepNull` and `mergeObjects` parameter. `keepNull` will also be automatically set to - `true`, so that null values are kept in the saved documents and not used to remove existing document fields (as for - default ArangoDB upsert behavior). - - `conflict` (default for the `Append` SaveMode): return a unique constraint violation error so that the insert operation fails -- `mergeObjects`: in case `overwriteMode` is set to `update`, controls whether objects (not arrays) will be merged. - - `true` (default): objects will be merged - - `false`: existing document fields will be overwritten -- `keepNull`: in case `overwriteMode` is set to `update` - - `true` (default): `null` values are saved within the document (by default) - - `false`: `null` values are used to delete the corresponding existing attributes -- `retry.maxAttempts`: max attempts for retrying write requests in case they are idempotent, `10` by default -- `retry.minDelay`: min delay in ms between write requests retries, `0` by default -- `retry.maxDelay`: max delay in ms between write requests retries, `0` by default - -### Write Resiliency - -The data of each partition is saved in batches using the ArangoDB API for -[inserting multiple documents](../http-api/documents.md#multiple-document-operations). -This operation is not atomic, therefore some documents could be successfully written to the database, while others could fail. To make the job more resilient to temporary errors (i.e. connectivity problems), in case of failure the request will be retried (with another Coordinator), if the provided configuration allows idempotent requests, namely: -- the schema of the dataframe has a **not nullable** `_key` field and -- `overwriteMode` is set to one of the following values: - - `replace` - - `ignore` - - `update` with `keep.null=true` - -A failing batch-saving request is retried once for every Coordinator. After that, if still failing, the write task for the related partition is aborted. According to the Spark configuration, the task can be retried and rescheduled on a different executor, if the provided write configuration allows idempotent requests (as described above). - -If a task ultimately fails and is aborted, the entire write job will be aborted as well. Depending on the `SaveMode` configuration, the following cleanup operations will be performed: -- `Append`: no cleanup is performed and the underlying data source may require manual cleanup. - `DataWriteAbortException` is thrown. -- `Overwrite`: the target collection will be truncated. -- `ErrorIfExists`: the target collection will be dropped. -- `Ignore`: if the collection did not exist before, it will be dropped; otherwise, nothing will be done. - -### Write requirements - -When writing to an edge collection (`table.type=edge`), the schema of the Dataframe being written must have: -- a non nullable string field named `_from`, and -- a non nullable string field named `_to` - -### Write Limitations - -- Batch writes are not performed atomically, so sometimes (i.e. in case of `overwrite.mode: conflict`) several documents in the batch may be written and others may return an exception (i.e. due to a conflicting key). -- Writing records with the `_key` attribute is only allowed on collections sharded by `_key`. -- In case of the `Append` save mode, failed jobs cannot be rolled back and the underlying data source may require manual cleanup. -- Speculative execution of tasks only works for idempotent write configurations. See [Write Resiliency](#write-resiliency) for more details. -- Speculative execution of tasks can cause concurrent writes to the same documents, resulting in write-write conflicts or lock timeouts - -## Mapping Configuration - -Serialization and deserialization of Spark Dataframe Row to and from JSON (or Velocypack) can be customized using the following options: -- `ignoreNullFields`: whether to ignore null fields during serialization, `false` by default (only supported in Spark 3.x) - -## Supported Spark data types - -The following Spark SQL data types (subtypes of `org.apache.spark.sql.types.Filter`) are supported for reading, writing and filter pushdown. - -- Numeric types: - - `ByteType` - - `ShortType` - - `IntegerType` - - `LongType` - - `FloatType` - - `DoubleType` - -- String types: - - `StringType` - -- Boolean types: - - `BooleanType` - -- Datetime types: - - `TimestampType` - - `DateType` - -- Complex types: - - `ArrayType` - - `MapType` (only with key type `StringType`) - - `StructType` - -## Connect to the Arango Managed Platform (AMP) - -To connect to SSL-secured deployments using X.509 Base64-encoded CA certificate (AMP): - -```scala -val options = Map( - "database" -> "", - "user" -> "", - "password" -> "", - "endpoints" -> ":", - "ssl.cert.value" -> "", - "ssl.enabled" -> "true", - "table" -> "" -) - -// read -val myDF = spark.read - .format("com.arangodb.spark") - .options(options) - .load() - -// write -import org.apache.spark.sql.DataFrame -val df: DataFrame = //... -df.write - .format("com.arangodb.spark") - .options(options) - .save() -``` - -## Current limitations - -- For `contentType=vpack`, implicit deserialization casts don't work well, i.e. - reading a document having a field with a numeric value whereas the related - read schema requires a string value for such a field. -- Dates and timestamps fields are interpreted to be in a UTC time zone. -- In read jobs using `stream=true` (default), possible AQL warnings are only - logged at the end of each read task (BTS-671). -- Spark SQL `DecimalType` fields are not supported in write jobs when using `contentType=json`. -- Spark SQL `DecimalType` values are written to the database as strings. -- `byteBatchSize` is only considered for `contentType=json` (DE-226) - -## Demo - -Check out our [demo](https://github.com/arangodb/arangodb-spark-datasource/tree/main/demo) -to learn more about ArangoDB Datasource for Apache Spark. diff --git a/site/content/arangodb/3.13/develop/integrations/arangodb-tinkerpop-provider.md b/site/content/arangodb/3.13/develop/integrations/arangodb-tinkerpop-provider.md deleted file mode 100644 index a1a68550bf..0000000000 --- a/site/content/arangodb/3.13/develop/integrations/arangodb-tinkerpop-provider.md +++ /dev/null @@ -1,841 +0,0 @@ ---- -title: ArangoDB TinkerPop Provider -menuTitle: TinkerPop Provider -weight: 10 -description: >- - Build graph applications using TinkerPop API with ArangoDB's high-performance backend, combining Gremlin traversals and native AQL queries ---- -ArangoDB TinkerPop Provider is an implementation of the [Apache TinkerPop OLTP Provider](https://tinkerpop.apache.org/docs/3.7.4/dev/provider) API for -ArangoDB. - -It allows using the standard TinkerPop API with ArangoDB as the backend storage. It supports creating, -querying, and manipulating graph data using the Gremlin traversal language, while offering the possibility to use native -AQL (ArangoDB Query Language) for complex queries. - -- Repository: -- [Code examples](https://github.com/arangodb/arangodb-tinkerpop-provider/tree/main/src/test/java/example) -- [Demo](https://github.com/arangodb/arangodb-tinkerpop-provider/tree/main/demo) -- [JavaDoc](https://www.javadoc.io/doc/com.arangodb/arangodb-tinkerpop-provider/latest/index.html) (generated reference documentation) -- [ChangeLog](https://github.com/arangodb/arangodb-tinkerpop-provider/blob/main/CHANGELOG.md) - -## Compatibility - -This Provider is compatible with: - -- Apache TinkerPop 3.7 -- ArangoDB 3.12+ -- ArangoDB Java Driver 7.22+ -- Java 8+ - -## Installation - -### Maven - -1. Check the [latest version](https://search.maven.org/artifact/com.arangodb/arangodb-tinkerpop-provider) available. -2. Add the following dependency to your `pom.xml` file: - -```xml - - - com.arangodb - arangodb-tinkerpop-provider - x.y.z - - -``` - -### Gradle - -1. Add the following dependency to your `build.gradle`: - -```groovy -implementation 'com.arangodb:arangodb-tinkerpop-provider:x.y.z' -``` - -### Gremlin Console - -1. Install the TinkerPop Provider in the Gremlin Console: - -```text -:install com.arangodb arangodb-tinkerpop-provider x.y.z -``` - -2. Restart the console to load the provider. - -3. Create a configuration for your ArangoDB connection. - -```text -gremlin> conf = [ -......1> "gremlin.graph":"com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph", -......2> "gremlin.arangodb.conf.graph.enableDataDefinition":"true", -......3> "gremlin.arangodb.conf.driver.hosts":"172.28.0.1:8529", -......4> "gremlin.arangodb.conf.driver.password":"test", -......5> ] -==>gremlin.graph=com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph -==>gremlin.arangodb.conf.graph.enableDataDefinition=true -==>gremlin.arangodb.conf.driver.hosts=172.28.0.1:8529 -==>gremlin.arangodb.conf.driver.password=test -``` -4. Open the graph using the configuration. - -```text -gremlin> graph = GraphFactory.open(conf) -==>arangodbgraph[ArangoDBGraphConfig{...}] -``` - -5. Create a traversal source and start using it: - -```text -gremlin> g = graph.traversal() -==>graphtraversalsource[arangodbgraph[...], standard] - -gremlin> g.addV("person").property("name", "marko") -==>v[4586117] - -gremlin> g.V().hasLabel("person").values("name") -==>marko -``` - -### Server Plugin - -Follow the steps below to set up the provider as a Gremlin Server plugin. - -1. Install the provider in the Gremlin Server: - - ```bash - ./bin/gremlin-server.sh install com.arangodb arangodb-tinkerpop-provider x.y.z - ``` - -2. Create a graph configuration file (e.g., `conf/arangodb.yaml`): - - ```yaml - gremlin: - graph: "com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph" - arangodb: - conf: - graph: - enableDataDefinition: true - driver: - hosts: - - "172.28.0.1:8529" - password: test - ``` - -3. Create a server configuration file to load the plugin and graph configuration (e.g., `conf/gremlin-server-arangodb.yaml`): - -```yaml -host: 0.0.0.0 -port: 8182 -graphs: { - graph: conf/arangodb.yaml} -scriptEngines: { - gremlin-groovy: { - plugins: { org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {}, - org.apache.tinkerpop.gremlin.tinkergraph.jsr223.TinkerGraphGremlinPlugin: {}, - com.arangodb.tinkerpop.gremlin.jsr223.ArangoDBGremlinPlugin: {}, - org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin: {classImports: [java.lang.Math], methodImports: [java.lang.Math#*]}, - org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {files: [scripts/empty-sample.groovy]}}}} -serializers: - - { className: org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV3, config: { ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3] }} # application/json - - { className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1 } # application/vnd.graphbinary-v1.0 - - { className: org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1, config: { serializeResultToString: true }} # application/vnd.graphbinary-v1.0-stringd -processors: - - { className: org.apache.tinkerpop.gremlin.server.op.session.SessionOpProcessor, config: { sessionTimeout: 28800000 }} - - { className: org.apache.tinkerpop.gremlin.server.op.traversal.TraversalOpProcessor} -``` - -4. Start the Gremlin Server with your configuration: - - ```bash - ./bin/gremlin-server.sh conf/gremlin-server-arangodb.yaml - ``` - -5. Connect to the server using the Gremlin Console: - - ```text - gremlin> :remote connect tinkerpop.server conf/remote.yaml - - gremlin> :remote console - ==>All scripts will now be sent to Gremlin Server - [localhost/127.0.0.1:8182] - type ':remote console' to return to local mode - ``` - -6. Start using the graph: - - ```text - gremlin> g.addV("person").property("name", "marko") - ==>v[4587713] - - gremlin> g.V().hasLabel("person").values("name") - ==>marko - ``` - -You can find the reference documentation [here](https://tinkerpop.apache.org/docs/3.7.4/reference/#_configuring_2). - - -## Quick Start - -Follow the steps below to get started with creating vertices, edges, and querying the graph. - -### Step 1: Configure and Create the Graph - -[//]: <> (@formatter:off) -```java -// Create a configuration -Configuration conf = new ArangoDBConfigurationBuilder() - .hosts("localhost:8529") - .user("root") - .password("test") - .db("myDatabase") - .name("myGraph") - .enableDataDefinition(true) // Allow creating database and graph if they don't exist - .build(); - -// Create a graph -ArangoDBGraph graph = (ArangoDBGraph) GraphFactory.open(conf); - -// Get a traversal source -GraphTraversalSource g = graph.traversal(); -``` -### Step 2: Add Vertices and Edges - -```java -// Add vertices with properties -Vertex person = g.addV("person") - .property("name", "Alice") - .property("age", 30) - .property("country", "Germany") - .next(); - -Vertex software = g.addV("software") - .property("name", "JArango") - .property("lang", "Java") - .next(); - -// Create relationships between vertices -Edge created = g.addE("created") - .from(person) - .to(software) - .property("year", 2025) - .next(); -``` - -### Step 3: Query the Graph - -```java -// Query the graph -List creators = g.V() - .hasLabel("software") - .has("name", "JArango") - .in("created") - .values("name") - .toList(); - -System.out.println("Creators: " + creators); - -// Query: Find all software created by Alice -List aliceSoftware = g.V() - .hasLabel("person") - .has("name", "Alice") - .out("created") - .values("name") - .toList(); - -System.out.println("aliceSoftware: " + aliceSoftware); - -``` - -### Step 4: Update Data - -```java -// Update a property -g.V() - .hasLabel("person") - .has("name", "Alice") - .property("age", 31) - .iterate(); - -// Remove a property -g.V() - .hasLabel("person") - .has("name", "Alice") - .properties("country") - .drop() - .iterate(); - -// Check the updated vertex -Map alice = g.V() - .hasLabel("person") - .has("name", "Alice") - .valueMap() - .next(); - -System.out.println("alice: " + alice); -``` - -### Step 5: Delete Data and Clean Up - -```java -// Remove an edge -g.E() - .hasLabel("created") - .where(__.outV() - .has("name", "Alice")) - .where(__.inV() - .has("name", "JArango")) - .drop() - .iterate(); - -// Remove a vertex (and its incident edges) -g.V() - .hasLabel("person") - .has("name", "Alice") - .drop() - .iterate(); - -// Close the graph when done -graph.close(); -``` -[//]: <> (@formatter:on) - -## Configuration - -The graph can be created using the methods from `org.apache.tinkerpop.gremlin.structure.util.GraphFactory.open(...)` -(see [javadoc](https://tinkerpop.apache.org/javadocs/3.7.4/full/org/apache/tinkerpop/gremlin/structure/util/GraphFactory.html)). -These methods accept a configuration file (e.g., YAML or properties file), a Java Map, or an Apache Commons Configuration object. - -The property `gremlin.graph` must be set to: `com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph`. - -Configuration examples can be found [here](https://github.com/arangodb/arangodb-tinkerpop-provider/tree/main/src/test/java/example). - -### Graph Configuration Properties - -Graph configuration properties are prefixed with `gremlin.arangodb.conf.graph`: - -| Property | Description | Default | -|----------------------------------------------------|---------------------------------------|-------------| -| `gremlin.arangodb.conf.graph.db` | ArangoDB database name | `_system` | -| `gremlin.arangodb.conf.graph.name` | ArangoDB graph name | `tinkerpop` | -| `gremlin.arangodb.conf.graph.enableDataDefinition` | Flag to allow data definition changes | `false` | -| `gremlin.arangodb.conf.graph.type` | Graph type: `SIMPLE` or `COMPLEX` | `SIMPLE` | -| `gremlin.arangodb.conf.graph.labelField` | Label field name | `_label` | -| `gremlin.arangodb.conf.graph.orphanCollections` | List of orphan collections names | - | -| `gremlin.arangodb.conf.graph.edgeDefinitions` | List of edge definitions | - | - -### Driver Configuration Properties - -Driver configuration properties are prefixed with `gremlin.arangodb.conf.driver`. All properties from -`com.arangodb.config.ArangoConfigProperties` are supported. See -the [ArangoDB Java Driver documentation](../drivers/java/reference-version-7/driver-setup.md#config-file-properties) -for details. - -### YAML Configuration - -```yaml -gremlin: - graph: "com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph" - arangodb: - conf: - graph: - db: "testDb" - name: "myFirstGraph" - enableDataDefinition: true - type: COMPLEX - orphanCollections: [ "x", "y", "z" ] - edgeDefinitions: - - "e1:[a]->[b]" - - "e2:[a,b]->[c,d]" - driver: - user: "root" - password: "test" - hosts: - - "172.28.0.1:8529" - - "172.28.0.1:8539" - - "172.28.0.1:8549" -``` - -Loading from a YAML file: - -[//]: <> (@formatter:off) -```java -ArangoDBGraph graph = (ArangoDBGraph) GraphFactory.open(""); -``` -[//]: <> (@formatter:on) - -### Programmatic Configuration - -1. Build the configuration using the configuration builder: - - [//]: <> (@formatter:off) - ```java - Configuration conf = new ArangoDBConfigurationBuilder() - .hosts("172.28.0.1:8529") - .user("root") - .password("test") - .database("testDb") - .name("myGraph") - .graphType(GraphType.SIMPLE) - .enableDataDefinition(true) - .build(); - ``` - [//]: <> (@formatter:on) - -2. Create the graph using the configuration: - - [//]: <> (@formatter:off) - ```java - ArangoDBGraph graph = (ArangoDBGraph) GraphFactory.open(conf); - ``` - [//]: <> (@formatter:on) - -### SSL Configuration - -To use TLS-secured connections to ArangoDB, follow these steps: - -1. Enable SSL by setting `gremlin.arangodb.conf.driver.useSsl` to `true` in your configuration. - -2. Configure SSL properties as needed (see [ArangoDB Java Driver documentation](../drivers/java/reference-version-7/driver-setup.md#config-file-properties) for all available options): - - ```yaml - gremlin: - graph: "com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph" - arangodb: - conf: - driver: - hosts: - - "172.28.0.1:8529" - useSsl: true - verifyHost: false - sslCertValue: "MIIDezCCAmOgAwIBAgIEeDCzXzANBgkqhkiG9w0BAQsFADBuMRAwDgYDVQQGEwdVbmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYDVQQKEwdVbmtub3duMRAwDgYDVQQLEwdVbmtub3duMRIwEAYDVQQDEwlsb2NhbGhvc3QwHhcNMjAxMTAxMTg1MTE5WhcNMzAxMDMwMTg1MTE5WjBuMRAwDgYDVQQGEwdVbmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYDVQQKEwdVbmtub3duMRAwDgYDVQQLEwdVbmtub3duMRIwEAYDVQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC1WiDnd4+uCmMG539ZNZB8NwI0RZF3sUSQGPx3lkqaFTZVEzMZL76HYvdc9Qg7difyKyQ09RLSpMALX9euSseD7bZGnfQH52BnKcT09eQ3wh7aVQ5sN2omygdHLC7X9usntxAfv7NzmvdogNXoJQyY/hSZff7RIqWH8NnAUKkjqOe6Bf5LDbxHKESmrFBxOCOnhcpvZWetwpiRdJVPwUn5P82CAZzfiBfmBZnB7D0l+/6Cv4jMuH26uAIcixnVekBQzl1RgwczuiZf2MGO64vDMMJJWE9ClZF1uQuQrwXF6qwhuP1Hnkii6wNbTtPWlGSkqeutr004+Hzbf8KnRY4PAgMBAAGjITAfMB0GA1UdDgQWBBTBrv9Awynt3C5IbaCNyOW5v4DNkTANBgkqhkiG9w0BAQsFAAOCAQEAIm9rPvDkYpmzpSIhR3VXG9Y71gxRDrqkEeLsMoEyqGnw/zx1bDCNeGg2PncLlW6zTIipEBooixIE9U7KxHgZxBy0Et6EEWvIUmnr6F4F+dbTD050GHlcZ7eOeqYTPYeQC502G1Fo4tdNi4lDP9L9XZpf7Q1QimRH2qaLS03ZFZa2tY7ah/RQqZL8Dkxx8/zc25sgTHVpxoK853glBVBs/ENMiyGJWmAXQayewY3EPt/9wGwV4KmU3dPDleQeXSUGPUISeQxFjy+jCw21pYviWVJTNBA9l5ny3GhEmcnOT/gQHCvVRLyGLMbaMZ4JrPwb+aAtBgrgeiK4xeSMMvrbhw==" - ``` - -3. Alternatively, use system properties for truststore configuration. If no `sslCertValue` is provided, the default SSL context is used. In such cases, you can specify the truststore using system properties: - - `javax.net.ssl.trustStore` - - `javax.net.ssl.trustStorePassword` - -### Data Definition Management - -The provider follows this process when instantiating a graph: - -1. **Validation**: The provider compares existing data definitions in ArangoDB with the structure expected by your configuration. It checks whether: - - The database exists - - The graph exists - - The graph structure has the same edge definitions and orphan collections - -2. **Error handling**: If there's a mismatch, an error is thrown and the graph is not instantiated. - -3. **Automatic creation** (optional): To automatically create missing data definitions, set `gremlin.arangodb.conf.graph.enableDataDefinition` to `true`. This allows: - - Creating a new database if it doesn't exist - - Creating a new graph if it doesn't exist (along with vertex and edge collections) - -{{< info >}} -Existing graphs are never modified automatically for safety reasons. -{{< /info >}} - -## Graph Types - -The ArangoDB TinkerPop Provider supports two graph types, which can be configured with the property -`gremlin.arangodb.conf.graph.type`: `SIMPLE` and `COMPLEX`. - -### SIMPLE Graph Type - -From an application perspective, this is the most flexible graph type that is backed by an ArangoDB graph composed of only one vertex collection and one edge definition. - -The `label` of each element is stored in a database document field. The label field name is configurable by setting the configuration property `graph.labelField`, `_label` by default. - -The `SIMPLE` graph type is the default graph type. - -It has the following advantages: - -- It closely matches the TinkerPop property graph -- It is simpler to get started and run examples -- It imposes no restrictions about element IDs -- It supports arbitrary labels, i.e., labels not known at graph construction time - -It has the following disadvantages: - -- All vertex types will be stored in the same vertex collection -- All edge types will be stored in the same edge collection -- It could not leverage the full potential of ArangoDB graph traversal -- It could require an index on the label field to improve performance - -Example configuration: - -```yaml -gremlin: - graph: "com.arangodb.tinkerpop.gremlin.structure.ArangoDBGraph" - arangodb: - conf: - graph: - db: "db" - name: "myGraph" - type: SIMPLE - edgeDefinitions: - - "e:[v]->[v]" -``` - -If `edgeDefinitions` are not configured, the default names are used: - -- `vertex` will be used for the vertex collection -- `edge` will be used for the edge collection - -Using a `SIMPLE` graph configured as in the example above and creating a new element like: - -[//]: <> (@formatter:off) -```java -graph.addVertex(T.label, "person", T.id, "foo"); -``` -[//]: <> (@formatter:on) - -would result in creating a document in the vertex collection `v` with `_key` equals to `foo` (and `_id` equals -to `v/foo`). - -### COMPLEX Graph Type - -The `COMPLEX` graph type is backed by an ArangoDB graph composed potentially of multiple vertex collections and multiple -edge definitions. - -The `label` of each element is used as name for the related database collection. - -It has the following advantages: - -- It closely matches the ArangoDB graph structure -- It allows multiple vertex collections and multiple edge collections -- It partitions the data in a finer way -- It allows indexing and sharding collections independently -- It is more flexible to match pre-existing database graph structures - -But on the other side has the following constraints: - -- Element IDs must have the format: `