40:null 41:["$","title",null,{"children":"Using ArangoDB in Observable Notebooks | Ross Mills | Observable"}] 47:T476,md`# Using ArangoDB in Observable Notebooks 🥑 In this notebook, we'll look at how to set up ArangoDB for use in Observable notebooks and how you can use the [official JavaScript driver](https://github.com/arangodb/arangojs) to connect to ArangoDB and execute queries. ArangoDB is a multi-model database functioning as a graph database, document database and key-value store all at the same time. The built-in AQL query language provides a combination of SQL-like joins, projections, basic statistical functions, as well as graph traversals, making it a great choice as an analytical database. Communication with ArangoDB is done through a REST API, lending itself nicely to integrating into Observable notebooks for data exploration and analysis use cases. You can learn more about ArangoDB on [their website](https://www.arangodb.com/), and the [AQL query language documentation](https://www.arangodb.com/docs/stable/aql/). Pulling data from an ArangoDB database in an Observable notebook is as easy as slicing through ripe avocado (but don't [hurt yourself](https://www.hss.edu/playbook/avocado-alert-hand-injuries-on-the-rise/)). `48:[] 45:{"id":"10129fd3abb20576","slug":"using-arangodb-in-observable-notebooks","title":"Using ArangoDB in Observable Notebooks","thumbnail":"cfe395012621ac21efe3deeb82ea9aa31f52725051f8ac7bc1bb8c2147dca433","access_level":"public","create_time":"$D2020-12-01T21:06:49.039Z","update_time":"$D2023-04-17T11:53:48.746Z","view_time":null,"first_public_time":"$D2020-12-04T13:57:50.916Z","has_unpublished_edits":null,"fork":false,"stars":1,"starred":false,"owner":{"type":"team","id":"55e9268ccca383a5","login":"rossmills99","name":"Ross Mills","avatar_url":"https://avatars-next.observableusercontent.com/edf6d8f13cc81ae6ed5c2a7f7911f9b522006a0413d822217f3666daf05d1366","tier":"starter_2024","bio":"Software engineer and hands-on tech leader. Creating and collaborating on interesting software projects gets me out of bed in the morning.","following":false},"version":546,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"3d55deecec17df75","login":"rossmills99","name":"Ross Mills","avatar_url":"https://avatars-next.observableusercontent.com/edf6d8f13cc81ae6ed5c2a7f7911f9b522006a0413d822217f3666daf05d1366","tier":null,"bio":"Software engineer and hands-on tech leader.\n","following":false}],"members":[{"type":"individual","id":"3d55deecec17df75","login":"rossmills99","name":"Ross Mills","avatar_url":"https://avatars-next.observableusercontent.com/edf6d8f13cc81ae6ed5c2a7f7911f9b522006a0413d822217f3666daf05d1366","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":1,"collection":{"id":"b66cf728a6a7a42c","slug":"arangodb","title":"ArangoDB","owner":{"id":"55e9268ccca383a5","login":"rossmills99","name":"Ross Mills"}},"type":"notebook","body":{"titling":"auto","title":"Using ArangoDB in Observable Notebooks","cells":[{"id":0,"value":"$47","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":222,"value":"md`## Run ArangoDB\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":303,"value":"{\n let el;\n if (!checkDatabase) {\n el = html`\n

👎

The database is not set up yet, or else the notebook can't connect to it yet.
Follow these instructions for setting up and running ArangoDB, then refresh the page.

`;\n el.classList.add('warn');\n }\n else {\n el = html`\n

👍

Looks like your database is running already so you might like to skip the rest of this section.

`;\n el.classList.add('info');\n }\n el.classList.add('box');\n return el;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":345,"value":"md`\nTo quickly get started with a database that can be used with this notebook, you can run ArangoDB in Docker using the following command:\n\n\\`\\`\\`bash\ndocker run -e ARANGO_ROOT_PASSWORD=test123 -p 8529:8529 -d arangodb/arangodb arangod --http.trusted-origin \"${origin}/\"\n\\`\\`\\`\n\nNote that the data you add to ArangoDB running in the Docker container will be lost when the container is stopped, unless you configure it to write to a persistent volume. You can read about how to configure that [here](https://www.arangodb.com/docs/3.7/deployment-docker.html).\n\nOtherwise, it couldn't be easier to install ArangoDB for Windows, MacOS or various Linux distros following [the instructions](https://www.arangodb.com/download-major/) according to your platform. Once installed, you'll need to set up CORS to make your database accessible from this notebook.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":9,"value":"cors = md`### CORS\n\nBefore you can access ArangoDB from an Observable notebook, you need to configure CORS on the ArangoDB server. The requests from your notebook are emitted from the iframe that runs your notebook code. That will have an origin something like:\n\n\\`\\`\\`\nhttps://.static.observableusercontent.com\n\\`\\`\\`\n\nYou can find this out from the \\`location.origin\\` browser global:`\n","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":482,"value":"origin = location.origin","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":485,"value":"md`\nWe need to set ArangoDB to accept requests coming from that origin, so we can make requests from our notebook. To do that, the [ArangoDB documentation](https://www.arangodb.com/docs/3.7/http/general.html#cross-origin-resource-sharing-cors-requests) says we should provide a startup option when running arangod like this:\n\n> \\`--http.trusted-origin \"https://rossmills99.static.observableusercontent.com/\"\\`\n>\n\nOr instead, you can add the following to your \\`arangod.conf\\` configuration file, then restart the arangod process:\n\n> \\`\\`\\`\n> [http]\n> trusted-origin = https://rossmills99.static.observableusercontent.com/\n> \\`\\`\\`\n\nNote - no quotes should be used around the value in the config file.\n\nWith ArangoDB setup to accept requests from your notebook, we're ready to start using it!\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":403,"value":"usingArangojs = md`## Using ArangoDB JavaScript Driver`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":438,"value":"md`ArangoDB has a REST API but rather than hand-code HTTP requests, we can use the existing JavaScript driver.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":441,"value":"md`### Import the arangojs library into the notebook\n\nHere's how we can import the library to use in a notebook:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":4,"value":"arangojs = require('arangojs@7.2.0/web.js')","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":416,"value":"md`By the way, if you're ever trying to work out how to import a JavaScript library, the [Module Require Debugger](https://observablehq.com/@observablehq/module-require-debugger) is fantastically useful!`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":60,"value":"md`### Get a Database Instance\n\nTo interact with ArangoDB, we need to create a \\`Database\\` object which encapsulates connection information like the database URL and credentials. Remember not to post your credentials in a public notebook! You might consider using Observable's [secrets](https://observablehq.com/@observablehq/secrets) feature to store your credentials.\n\nHere's how we're setting it up for this notebook. The database is called 'NotebookTest' and we're setting up our connection to use some basic auth credentials.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":273,"value":"md`\n\\`\\`\\`javascript\ndb = new arangojs.Database('http://localhost:8529');\n db.useDatabase('NotebookTest');\n db.useBasicAuth('root', 'test123');\n return db;\n\\`\\`\\`\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":28,"value":"db = { \n // This line just sets up the test database for the cells in this notebook.\n await setupTestDatabase();\n \n const db = new arangojs.Database('http://localhost:8529');\n db.useDatabase('NotebookTest');\n db.useBasicAuth('root', 'root');\n return db;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":33,"value":"md`\n### Test the connection\n\nTo test the connection, try a simple request, like this one which fetches details about the collections in the current database:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":35,"value":"collections = db.listCollections()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":97,"value":"md`\n### A note on Observable and async magic\n\nThe \\`arangojs\\` API calls are all async - they return promises - but notice we don't need to call \\`await\\` to get the result. That's just a bit of Observable magic going on. Promises are automatically resolved to their underlying values. In a code block, you might have more than one request using arangojs and then you might use \\`await\\` to make sure one request finished before the next one begins.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":107,"value":"md`## Execute AQL Queries\n\nIf the request to get collections worked OK then you are in business! Now let's execute some queries.\n\nThe arangojs driver comes with a tagged template function called [\\`aql\\`](https://arangodb.github.io/arangojs/latest/modules/_aql_.aql.html) that can be used to easily create safe, parameterized AQL queries.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":117,"value":"aql = arangojs.aql","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":122,"value":"md`Here we set up an example using Observable's \\`viewof\\` and a simple HTML text input to capture user input, which is then applied in a query to ArangoDB. \n\n**Note**: a request goes to the database for every change in the input, which is not ideal - you might want to throttle those requests a bit in a real application.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":132,"value":"viewof filterText = html``","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":467,"value":"cloudsDisplay = {\n return md`\n**Search results:**\n${clouds.map(c => '- ' + c.name).join('\\n')}\n`\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":159,"value":"md`The \\`cloudsQuery\\` is listed separately to the query result, to show how the \\`aql\\` template function builds the parameterized query and its parameters out of the supplied template string. Try typing \"Cumulus\" in the cloud search input above, and notice how \\`cloudsQuery.bindVars\\` is updated.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":131,"value":"cloudsQuery = {\n const query = aql`\n FOR cloud IN Clouds\n FILTER !${filterText} OR CONTAINS(cloud.name, ${filterText})\n RETURN cloud`;\n return query;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":175,"value":"md`We can execute the query by passing it into the \\`db.query\\` function. Notice we use \\`await\\` this time because we want the result of \\`all()\\`, instead of the response object itself.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":144,"value":"clouds = (await db.query(cloudsQuery)).all();","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":185,"value":"md`What we then see are the results of the query updating in real time as you change the filter text in the input above.\n\nAnd now you know how to query ArangoDB directly from an Observable notebook, happy days.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":296,"value":"md`\n---\n## Appendix`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":327,"value":"checkDatabase = {\n const db = new arangojs.Database('http://localhost:8529');\n db.useDatabase('_system');\n db.useBasicAuth('root', 'root');\n try {\n const dbs = await db.listDatabases();\n return true;\n }\n catch {\n return false;\n }\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":236,"value":"async function setupTestDatabase() {\n if (!checkDatabase) return;\n \n const systemDb = new arangojs.Database('http://localhost:8529');\n systemDb.useDatabase('_system');\n systemDb.useBasicAuth('root', 'test123');\n \n const dbs = await systemDb.listDatabases();\n let testDb;\n if (!dbs.includes('NotebookTest')) {\n testDb = await systemDb.createDatabase('NotebookTest');\n }\n else {\n testDb = systemDb.database('NotebookTest');\n }\n \n const clxs = await testDb.listCollections();\n if (!clxs.map(clx => clx.name).includes('Clouds')) {\n const cloudsClx = await testDb.createCollection('Clouds');\n await cloudsClx.saveAll([\n {\"name\":\"Cumulus mediocris\"},\n {\"name\":\"cumulus humilis\"},\n {\"name\":\"nimbostratus\"},\n {\"name\":\"cumulonimbus calvus\"},\n {\"name\":\"cumulonimbus capillatus\"},\n {\"name\":\"altostratus\"}]);\n }\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":499,"value":"nbStyle = {\n return html`\n`\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W48","stdlib":"1"}} 46:"$45:body"