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.
On this shell's prompt, you can issue arbitrary JavaScript commands. So you are able to do things like...:
number = 123;
number = number * 10;
You can access previously run commands using the up and down keys. It saves you from retyping 'tutorial' every time for instance.
You can also run more complex instructions, such as for loops:
for (var i = 0; i < 10; i++) { number = number + 1; }
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"); }
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.
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.
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).
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 })
};
You want to take a look at your documents? No problem:
db.places.toArray();
To see how many documents there are in a collection, use the 'count' method:
db.places.count();
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");
The '_id' attribute can also be used to retrieve documents using the 'db' object:
db._document("places/foo");
db._document("places/example5");
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");
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.
Deleting single documents can be achieved by providing the document _id or _key:
db._remove("places/example7");
db.places.remove("example8");
db.places.count();
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();
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/
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");