mirror of https://gitee.com/bigwinds/arangodb
227 lines
8.3 KiB
Plaintext
227 lines
8.3 KiB
Plaintext
|
||
!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, an array 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 an array 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.
|
||
|
||
|