!CHAPTER Exploring Collections and Documents

ArangoDB is a database that serves documents to clients.

* A *document* contains zero or more attributes, each one of these
  attributes has a value. A value can either be an atomic type, i. e.
  integer, strings, boolean, a list or an embedded document. Documents
  are normally represented as JSON objects
* Documents are grouped into *collections*. A collection contains zero
  or more documents
* *Queries* are used to filter documents based on certain criteria.
  Queries can be as simple as a "query by example" or as complex as
  ["joins"](../AqlExamples/Join.md) using many collections or graph structures
* *Cursors* are used to iterate over the result of a query
* *Indexes* are used to speed up of searches. There are various different
  types of indexes like [hash indexes](../IndexHandling/Hash.md) and [geo indexes](../IndexHandling/Geo.md)

If you are familiar with RDBMS then it is safe to compare collections
to tables and documents to rows. However, bringing structure to the
"rows" has many advantages - as you will see later.

!SECTION Starting the JavaScript shell

The easiest way to connect to the database is the JavaScript shell
_arangosh_. You can either start it from the command-line or as an
embedded version in the browser. Using the command-line tool has the
advantage that you can use autocompletion.

    unix> arangosh --server.password ""
                                           _     
      __ _ _ __ __ _ _ __   __ _  ___  ___| |__  
     / _` | '__/ _` | '_ \ / _` |/ _ \/ __| '_ \ 
    | (_| | | | (_| | | | | (_| | (_) \__ \ | | |
     \__,_|_|  \__,_|_| |_|\__, |\___/|___/_| |_|
                           |___/                 

    Welcome to arangosh 1.x.y. Copyright (c) 2012 triAGENS GmbH.
    Using Google V8 3.9.4 JavaScript engine.
    Using READLINE 6.1.

    Connected to Arango DB 127.0.0.1:8529 Version 2.2.0

    ------------------------------------- Help -------------------------------------
    Predefined objects:                                                 
      arango:                               ArangoConnection           
      db:                                   ArangoDatabase             
      fm:                                   FoxxManager  
    Example:                                                            
     > db._collections();                   list all collections       
     > db._create(<name>)                   create a new collection    
     > db._drop(<name>)                     drop a collection         
     > db.<name>.toArray()                  list all documents         
     > id = db.<name>.save({ ... })         save a document            
     > db.<name>.remove(<_id>)              delete a document          
     > db.<name>.document(<_id>)            retrieve a document        
     > db.<name>.replace(<_id>, {...})      overwrite a document       
     > db.<name>.update(<_id>, {...})       partially update a document
     > db.<name>.exists(<_id>)              check if document exists   
     > db._query(<query>).toArray()         execute an AQL query       
     > db._useDatabase(<name>)              switch database            
     > db._createDatabase(<name>)           create a new database      
     > db._listDatabases()                  list existing databases    
     > help                                 show help pages            
     > exit                                         
    arangosh>

This gives you a prompt where you can issue JavaScript commands.

The standard setup does not require a password. Depending on your
setup you might need to specify the endpoint, username and password
in order to run the shell on your system. You can use the options
`--server.endpoint`, `--server.username` and `--server.password` for
this.

    unix> arangosh --server.endpoint tcp://127.0.0.1:8529 --server.username root

A default configuration is normally installed under
*/etc/arangodb/arangosh.conf*. It contains a default endpoint and an
empty password.

!SECTION Querying for Documents

All documents are stored in collections. All collections are stored in a
database. The database object is accessible via the variable *db*.

Creating a collection is simple. You can use the *_create* method
of the *db* variable.

    arangosh> db._create("example");
    [ArangoCollection 70628, "example" (status loaded)]

After the collection has been created you can easily access it using
the path *db.example*. The collection currently shows as *loaded*,
meaning that it's loaded into memory. If you restart the server and
access the collection again it will now show as *unloaded*. You can
also manually unload a collection.

    arangosh> db.example.unload();
    arangosh> db.example;
    [ArangoCollection 70628, "example" (status unloaded)]

Whenever you use a collection ArangoDB will automatically load it
into memory for you.

In order to create new documents in a collection use the *save*
operation. 

    arangosh> db.example.save({ Hello : "World" });
    { "error" : false, "_id" : "example/1512420", "_key" : "1512420", "_rev" : "1512420" }
    arangosh> db.example.save({ "name" : "John Doe", "age" : 29 });
    { "error" : false, "_id" : "example/1774564", _key : "1774564", "_rev" : "1774564" }
    arangosh> db.example.save({ "name" : "Jane Smith", "age" : 31 });
    { "error" : false, "_id" : "example/1993214", "_key" : "1993214", "_rev" : "1993214" }

Just storing documents would be no fun. We now want to select some of
the stored documents again.  In order to select all elements of a
collection, one can use the *toArray* method:

    arangosh> db.example.toArray()
    [
      { 
        "_id" : "example/1993214", 
        "_key" : "1993214",
        "_rev" : "1993214",
        "age" : 31, 
        "name" : "Jane Smith"
      }, 
      { 
        "_id" : "example/1774564", 
        "_key" : "1774564",
        "_rev" : "1774564", 
        "age" : 29, 
        "name" : "John Doe"
      }, 
      { 
        "_id" : "example/1512420", 
        "_key" : "1512420",
        "_rev" : "1512420", 
        "Hello" : "World"
      }
    ]

The last document was a mistake – so let's delete it:

    arangosh> db.example.remove("example/1512420")
    true
    arangosh> db.example.toArray()
    [
      { 
        "_id" : "example/1993214", 
        "_key" : "1993214",
        "_rev" : "1993214",
        "age" : 31, 
        "name" : "Jane Smith"
      }, 
      { 
        "_id" : "example/1774564", 
        "_key" : "1774564",
        "_rev" : "1774564", 
        "age" : 29, 
        "name" : "John Doe"
      }
    ]

Now we want to look for a person with a given name. We can use
*byExample* for this. The method returns a list of documents
matching a given example.

    arangosh> db.example.byExample({ name: "Jane Smith" }).toArray()
    [
      { 
        "_id" : "example/1993214", 
        "_key" : "1993214",
        "_rev" : "1993214",
        "age" : 31, 
        "name" : "Jane Smith"
      }
    ]

While the *byExample* works very well for simple queries where you
combine the conditions with an `and`. The syntax above becomes messy for *joins*
and *or* conditions. Therefore ArangoDB also supports a full-blown
query language, AQL. To run an AQL query, use the *db._query* method:.

    arangosh> db._query('FOR user IN example FILTER user.name == "Jane Smith" RETURN user').toArray()
    [
      { 
        "_id" : "example/1993214", 
        "_key" : "1993214",
        "_rev" : "1993214",
        "age" : 31, 
        "name" : "Jane Smith"
      }
    ]

Searching for all persons with an age above 30:

    arangosh> db._query('FOR user IN example FILTER user.age > 30 RETURN user').toArray()
    [
      { 
        "_id" : "example/1993214", 
        "_key" : "1993214",
        "_rev" : "1993214",
        "age" : 31, 
        "name" : "Jane Smith"
      }
    ]

You can learn all about the query language [Aql](../Aql/README.md). Note that
*_query* is a short-cut for *_createStatement* and *execute*. We will
come back to these functions when we talk about cursors.

!SECTION ArangoDB's Front-End

The ArangoDB server has a graphical front-end, which allows you to
inspect the current state of the server from within your browser. You
can use the front-end using the following URL:

    http://localhost:8529/

The front-end allows you to browse through the collections and
documents. If you need to administrate the database, please use
the ArangoDB shell described in the next section.