Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
arangodb/Documentation/UserManual/FirstStepsArangoDB.md

584 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

First Steps with ArangoDB {#FirstStepsArangoDB}
===============================================
@NAVIGATE_FirstStepsArangoDB
@EMBEDTOC{FirstStepsArangoDBTOC}
What is ArangoDB? {#FirstStepsArangoDBIntro}
============================================
For installation instructions, please refer to the
@S_EXTREF_S{InstallManual.html,installation manual}
ArangoDB is a multi-purpose open-source database with a flexible data
model for documents, graphs, and key-values. You can easily build high
performance applications using a convenient
@ref Aql "SQL-like query language" or @ref UserManualFoxxManager
"JavaScript" and mruby extensions.
The database server _arangod_ stores all documents and serves them
using a REST interface. There are drivers for all major languages like
Ruby, Python, PHP, JavaScript, and Perl. In the following sections we
will use the JavaScript shell to communicate with the database and
demonstrate some of ArangoDB's features using JavaScript.
Key features include:
- *Schema-free schemata*: Let you combine the space efficiency of MySQL with
the performance power of NoSQL
- *Application server*: Use ArangoDB as an application server and fuse your application and
database together for maximal throughput
- *JavaScript for all*: No language zoo, you can use one language from your
browser to your back-end
- *Flexible data modeling*: Model your data as combination of key-value pairs,
documents or graphs - perfect for social relations
- *Free index choice*: Use the correct index for your problem, be it a skip
list or a fulltext search
- *Configurable durability*: Let the application decide if it needs more
durability or more performance
- *No-nonsense storage*: ArangoDB uses all of the power of modern storage
hardware, like SSD and large caches
- *Powerful query language* (AQL) to retrieve data
- *Transactions*: Run queries on multiple documents or collections with
optional transactional consistency and isolation
- *Replication*: Set up the database in a master-slave configuration
- It is open source (*Apache Licence 2.0*)
For more in-depth information:
- Read more on the
@S_EXTREF_S{http://www.arangodb.org/2012/03/07/avocadodbs-design-objectives,design goals}
of ArangoDB
- @EXTREF{http://vimeo.com/36411892,Watch the video}: Martin Schönert,
architect of ArangoDB, gives an introduction of what the ArangoDB project
is about
- Or give it a @S_EXTREF{http://www.arangodb.org/try,try}
ArangoDB programs {#FirstStepsArangoDBBinaries}
===============================================
The ArangoDB database package comes with the following programs:
- _arangod_: The ArangoDB database daemon. This server program is
intended to run as daemon process and to server the various clients
connection to the server via TCP / HTTP. See @ref
FirstStepsServerStartStop
- _arangosh_: The ArangoDB shell. A client that implements a
read-eval-print loop (REPL) and provides functions to access and
administrate the ArangoDB server. See @ref FirstStepsShellStartStop.
- _arangoimp_: A bulk importer for the ArangoDB server
See @ref ImpManual
- _arangodump_: A tool to create backups of an ArangoDB database. See
@ref DumpManual
- _arangorestore_: A tool to reload data from a backup into an ArangoDB database.
See @ref RestoreManual
- _foxx-manager_: A shell script to administer Foxx applications.
See @ref UserManualFoxxManager
- _arango-dfdb_: A datafile debugger for ArangoDB. It is intended to be
used primarily during development of ArangoDB. See @ref DbaManualDatafileDebugger
Getting familiar with ArangoDB {#FirstStepsArangoDBServerStart}
===============================================================
First of all download and install the corresponding RPM or Debian package or use
homebrew on the MacOS X. See the @S_EXTREF_S{InstallManual.html, installation
manual} for more details. In case you just want to experiment with ArangoDB you
can use the @S_EXTREF_S{http://www.arangodb.org/try,online} demo without
installing ArangoDB locally.
For Linux:
- Visit the official ArangoDB download page at
@S_EXTREF_S{http://www.arangodb.org/download,http://www.arangodb.org/download}
and download the correct package for your Linux distribution
- Install the package using your favorite package manager
- Start up the database server, normally this is done by
executing `/etc/init.d/arangod start`. The exact command
depends on your Linux distribution
For MacOS X:
- Execute `brew install arangodb`
- And start the server using `/usr/local/sbin/arangod &`
For Microsoft Windows:
- Visit the official ArangoDB download page at
@S_EXTREF_S{http://www.arangodb.org/download,http://www.arangodb.org/download}
and download the installer for Windows
- Start up the database server
After these steps there should be a running instance of _arangod_ -
the ArangoDB database server.
unix> ps auxw | fgrep arangod
arangodb 14536 0.1 0.6 5307264 23464 s002 S 1:21pm 0:00.18 /usr/local/sbin/arangod
If there is no such process, check the log file
`/var/log/arangodb/arangod.log` for errors. If you see a log message
like
2012-12-03T11:35:29Z [12882] ERROR Database directory version (1) is lower than server version (1.2).
2012-12-03T11:35:29Z [12882] ERROR It seems like you have upgraded the ArangoDB binary. If this is what you wanted to do, please restart with the --upgrade option to upgrade the data in the database directory.
2012-12-03T11:35:29Z [12882] FATAL Database version check failed. Please start the server with the --upgrade option
make sure to start the server once with the `--upgrade` option.
Exploring Collections and Documents {#FirstStepsArangoDBFirstSteps}
===================================================================
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 @ref SimpleQueryByExample "query by example" or as complex as
@ref AqlExamplesJoins "joins" 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 @ref IndexHash, @ref IndexGeo and @ref IndexBitArray
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.
Starting the JavaScript shell {#FirstStepsArangoDBConnecting}
-------------------------------------------------------------
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 1.x.y
------------------------------------- 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.
Troubleshooting {#FirstStepsArangoDBTroubleShooting}
----------------------------------------------------
If the ArangoDB server does not start or if you cannot connect to it
using `arangosh` or other clients, you can try to find the problem cause by
executing the following steps. If the server starts up without problems,
you can skip this section.
* *Check the server log file*: If the server has written a log file you should
check it because it might contain relevant error context information.
* *Check the configuration*: The server looks for a configuration file
named `arangod.conf` on startup. The contents of this file will be used
as a base configuration that can optionally be overridden with command-line
configuration parameters. You should check the config file for the most
relevant parameters such as:
* `server.endpoint`: What IP address and port to bind to
* `log parameters`: If and where to log
* `database.directory`: Path the database files are stored in
If the configuration reveals that something is not configured right the config
file should be adjusted and the server be restarted.
* *Start the server manually and check its output*: Starting the server might
fail even before logging is activated so the server will not produce log
output. This can happen if the server is configured to write the logs to
a file that the server has no permissions on. In this case the server
cannot log an error to the specified log file but will write a startup
error on stderr instead.
Starting the server manually will also allow you to override specific
configuration options, e.g. to turn on/off file or screen logging etc.
* *Check the TCP port*: If the server starts up but does not accept any incoming
connections this might be due to firewall configuration between the server
and any client(s). The server by default will listen on TCP port 8529. Please
make sure this port is actually accessible by other clients if you plan to use
ArangoDB in a network setup.
When using hostnames in the configuration or when connecting, please make
sure the hostname is actually resolvable. Resolving hostnames might invoke
DNS, which can be a source of errors on its own.
It is generally good advice to not use DNS when specifying the endpoints
and connection addresses. Using IP addresses instead will rule out DNS as
a source of errors. Another alternative is to use a hostname specified
in the local `/etc/hosts` file, which will then bypass DNS.
* *Test if `curl` can connect*: Once the server is started, you can quickly
verify if it responds to requests at all. This check allows you to
determine whether connection errors are client-specific or not. If at
least one client can connect, it is likely that connection problems of
other clients are not due to ArangoDB's configuration but due to client
or in-between network configurations.
You can test connectivity using a simple command such as:
`curl --dump - -X GET http://127.0.0.1:8529/_api/version && echo`
This should return a response with an `HTTP 200` status code when the
server is running. If it does it also means the server is generally
accepting connections. Alternative tools to check connectivity are `lynx`
or `ab`.
Querying for Documents {#FirstStepsArangoDBQuerying}
----------------------------------------------------
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 `all` operator. Because this might return
a lot of data, we switch on pretty printing before.
arangosh> start_pretty_print();
use pretty printing
The command `stop_pretty_print()` will switch off pretty printing again.
Now extract all elements:
arangosh> db.example.all().toArray()
[
{
_id : "example/6308263",
_key : "1993214",
_rev : "1993214",
age : 31,
name : "Jane Smith"
},
{
_id : "example/6242727",
_key : "1774564",
_rev : "1774564",
age : 29,
name : "John Doe"
},
{
_id : "example/5980583",
_key : "1512420",
_rev : "1512420",
Hello : "World"
}
]
The last document was a mistake – so let's delete it:
arangosh> db.example.remove("example/5980583")
true
arangosh> db.example.all().toArray()
[
{
_id : "example/6308263",
_key : "1993214",
_rev : "1993214",
age : 31,
name : "Jane Smith"
},
{
_id : "example/6242727",
_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/6308263",
_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.
arangosh> db._query('FOR user IN example FILTER user.name == "Jane Smith" RETURN user').toArray()
[
{
_id : "example/6308263",
_key : "1993214",
_rev : "1993214",
age : 31,
name : "Jane Smith"
}
]
Search for all persons over 30:
arangosh> db._query('FOR user IN example FILTER user.age > 30 RETURN user').toArray()
[
{
_id : "example/6308263",
_key : "1993214",
_rev : "1993214",
age : 31,
name : "Jane Smith"
}
]
You can learn all about the query language @ref Aql "here". Note that
`_query` is a short-cut for `_createStatement` and `execute`. We will
come back to these functions when we talk about cursors.
ArangoDB's Front-End {#FirstStepsArangoDBFE}
--------------------------------------------
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/_admin/html/index.html
Unless you have loaded an application into the ArangoDB server – which remaps
the paths – the front-end will also be available under
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.
Details about the ArangoDB Server {#FirstStepsServerStartStop}
==============================================================
The ArangoDB database server has two modes of operation: As a server, where it
will answer to client requests and as an emergency console, in which you can
access the database directly. The latter - as the name suggests - should
only be used in case of an emergency, for example, a corrupted
collection. Using the emergency console allows you to issue all commands
normally available in actions and transactions. When starting the server in
emergency console mode, the server cannot handle any client requests.
You should never start more than one server using the same database directory,
independent from the mode of operation. Normally ArangoDB will prevent
you from doing this by placing a lockfile in the database directory and
not allowing a second ArangoDB instance to use the same database directory
if a lockfile is already present.
The following command starts the ArangoDB database in server mode. You will
be able to access the server using HTTP requests on port 8529. See @ref
FirstStepsServerStartStopOptions "below" for a list of frequently used
options – see @ref CommandLine "here" for a complete list.
unix> /usr/local/sbin/arangod /tmp/vocbase
20ZZ-XX-YYT12:37:08Z [8145] INFO using built-in JavaScript startup files
20ZZ-XX-YYT12:37:08Z [8145] INFO ArangoDB (version 1.x.y) is ready for business
20ZZ-XX-YYT12:37:08Z [8145] INFO Have Fun!
After starting the server, point your favorite browser to:
http://localhost:8529/
to access the administration front-end.
Linux
-----
To start the server at system boot time you should use one of the
pre-rolled packages that will install the necessary start / stop
scripts for ArangoDB. You can use the start script as follows:
unix> /etc/init.d/arangod start
To stop the server you can use the following command:
unix> /etc/init.d/arangod stop
You may require root privileges to execute these commands.
If you compiled ArangoDB from source and did not use any installation
package – or using non-default locations and/or multiple ArangoDB
instances on the same host – you may want to start the server process
manually. You can do so by invoking the arangod binary from the command
line as shown before. To stop the database server gracefully, you can
either press CTRL-C or by send the SIGINT signal to the server process.
On many systems this can be achieved with the following command:
unix> kill -2 `pidof arangod`
Frequently Used Options {#FirstStepsServerStartStopOptions}
-----------------------------------------------------------
The following command-line options are frequently used. For a full
list of options see @ref CommandLine "here".
@CMDOPT{@CA{database-directory}}
Uses the @CA{database-directory} as base directory. There is an
alternative version available for use in configuration files, see @ref
CommandLineArangod "here".
@copydetails triagens::rest::ApplicationServer::_options
@CMDOPT{\--log @CA{level}}
Allows the user to choose the level of information which is logged by
the server. The @CA{level} is specified as a string and can be one of
the following values: fatal, error, warning, info, debug or trace. For
more information see @ref CommandLineLogging "here".
@copydetails triagens::rest::ApplicationEndpointServer::_endpoints
@copydetails triagens::arango::ArangoServer::_disableAuthentication
@copydetails triagens::rest::ApplicationEndpointServer::_keepAliveTimeout
@CMDOPT{\--daemon}
Runs the server as a daemon (as a background process).
Details about the ArangoDB Shell {#FirstStepsShellStartStop}
============================================================
After the server has been @ref FirstStepsServerStartStop "started",
you can use the ArangoDB shell (_arangosh_) to administrate the
server. Without any arguments, the ArangoDB shell will try to contact
the server on port 8529 on the localhost. For more information see
@ref UserManualArangosh. You might need to set additional options
(endpoint, username and password) when connecting:
unix> ./arangosh --server.endpoint tcp://127.0.0.1:8529 --server.username root
The shell will print its own version number and – if successfully connected
to a server – the version number of the ArangoDB server.
Command-Line Options {#FirstStepsShellStartStopOptions}
-------------------------------------------------------
Use `--help` to get a list of command-line options:
unix> ./arangosh --help
STANDARD options:
--audit-log <string> audit log file to save commands and results to
--configuration <string> read configuration file
--help help message
--max-upload-size <uint64> maximum size of import chunks (in bytes) (default: 500000)
--no-auto-complete disable auto completion
--no-colors deactivate color support
--pager <string> output pager (default: "less -X -R -F -L")
--pretty-print pretty print values
--quiet no banner
--temp-path <string> path for temporary files (default: "/tmp/arangodb")
--use-pager use pager
JAVASCRIPT options:
--javascript.check <string> syntax check code Javascript code from file
--javascript.execute <string> execute Javascript code from file
--javascript.execute-string <string> execute Javascript code from string
--javascript.startup-directory <string> startup paths containing the JavaScript files
--javascript.unit-tests <string> do not start as shell, run unit tests instead
--jslint <string> do not start as shell, run jslint instead
LOGGING options:
--log.level <string> log level (default: "info")
CLIENT options:
--server.connect-timeout <double> connect timeout in seconds (default: 3)
--server.disable-authentication <bool> disable authentication (default: false)
--server.endpoint <string> endpoint to connect to, use 'none' to start without a server (default: "tcp://127.0.0.1:8529")
--server.password <string> password to use when connecting (leave empty for prompt)
--server.request-timeout <double> request timeout in seconds (default: 300)
--server.username <string> username to use when connecting (default: "root")
@BNAVIGATE_FirstStepsArangoDB
Reference in New Issue View Git Blame Copy Permalink