Skip to content

Instantly share code, notes, and snippets.

@jperocho
Created June 18, 2018 06:36
Show Gist options
  • Save jperocho/893a52748a27349a99452e78a6565da6 to your computer and use it in GitHub Desktop.
Save jperocho/893a52748a27349a99452e78a6565da6 to your computer and use it in GitHub Desktop.
Arango Shell Tutorial

1. Welcome to the tutorial!

This is a user-interactive tutorial on ArangoDB and the ArangoDB shell. It will give you a first look into ArangoDB and how it works.

2. JavaScript Shell

On this shell's prompt, you can issue arbitrary JavaScript commands. So you are able to do things like...:

number = 123;
number = number * 10;

3. Shell History

You can access previously run commands using the up and down keys. It saves you from retyping 'tutorial' every time for instance.

4. Running Complex Instructions

You can also run more complex instructions, such as for loops:

for (var i = 0; i < 10; i++) { number = number + 1; }

5. Printing Results

As you see, the result of the last command executed is printed automatically. To explicitly print a value at any other time, there is the print function:

for (var i = 0; i < 5; ++i) { print("I am a JavaScript shell"); }

6. Creating Collections

ArangoDB is primarily a document database. This means that we store data as documents (which are similar to JavaScript objects) in so-called 'collections'. Let's create a collection named 'places' now:

db._create('places');

Note: each collection is identified by a unique name. Trying to create a collection that already exists will produce an error.

7. Displaying Collections

Now you can take a look at the collection(s) you just created:

db._collections();

Please note that all collections will be returned, including ArangoDB's pre-defined system collections.

8. Accessing a single collection

If you want to access a particular collection, you can either write:

db.places;

or the more elaborate alternative:

db._collection('places');

Both return a collection object (if the specified collection exists).

9. Creating Documents

We have a collection, but it is empty. So let's create some documents!

db.places.save({ _key : "foo", city : "foo-city" });
for (var i = 0; i <= 10; i++) {
  db.places.save({ _key: "example" + i, zipcode: i })
};

10. Displaying All Documents

You want to take a look at your documents? No problem:

db.places.toArray();

11. Counting Documents

To see how many documents there are in a collection, use the 'count' method:

db.places.count();

12. Retrieving Single Documents

As you can see, each document has some meta attributes '_id', '_key' and '_rev'. The '_key' attribute can be used to quickly retrieve a single document from a collection:

db.places.document("foo");
db.places.document("example5");

13. Retrieving Single Documents

The '_id' attribute can also be used to retrieve documents using the 'db' object:

db._document("places/foo");
db._document("places/example5");

14. Modifying Documents

You can modify existing documents. Try to add a new attribute to a document and verify whether it has been added:

db._update("places/foo", { zipcode: 39535 });
db._document("places/foo");

15. Document Revisions

Note that after updating the document, its '_rev' attribute changed automatically.

The '_rev' attribute contains a document revision number, and it can be used for conditional modifications. Here's an example of how to avoid lost updates in case multiple clients are accessing the documents in parallel:

doc = db._document("places/example1");
db._update("places/example1", { someValue: 23 });
db._update(doc, { someValue: 42 });

Note that the first update will succeed because it was unconditional.

The second update however is conditional because we're also passing the document's revision id in the first parameter to _update. As the revision id we're passing to update does not match the document's current revision anymore, the update is rejected.

16. Removing Documents

Deleting single documents can be achieved by providing the document _id or _key:

db._remove("places/example7");
db.places.remove("example8");
db.places.count();

17. Searching Documents

Searching for documents with specific attributes can be done by using the 'byExample' method:

db._create("users");
for (var i = 0; i < 10; ++i) {
  db.users.save({ name: "username" + i, active: (i % 3 == 0), age: 30 + i });
}
db.users.byExample({ active: false }).toArray();
db.users.byExample({ name: "username3", active: true }).toArray();

18. Running AQL Queries

ArangoDB also provides a query language (AQL) for more complex matching:

db._query(`
  FOR u IN users
    FILTER u.active == true && u.age >= 33
    RETURN { username: u.name, age: u.age }
`).toArray();

Wrapping multi-line queries in backticks is the most convenient way in today's JavaScript.

See our online documentation for more details on AQL: https:docs.arangodb.com/

19. Using Databases

By default, the ArangoShell connects to the default database. The default database is named '_system'. To create another database, use the '_createDatabase' method of the 'db' object. To switch to an existing database, use '_useDatabase':

db._createDatabase("mydb");
db._useDatabase("mydb");

To get rid of a database and all of its collections, use '_dropDatabase'. It needs to be called from within the '_system' database:

db._useDatabase("_system");
db._dropDatabase("mydb");
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment