1
0
Fork 0

Minor documentation changes, part 1 (from devel, squashed): (#3957)

* Add WITH to graph traversal syntax

* State clearer what where whitespace is ignored in conf files

* Add cross-references between POSITION() and CONTAINS()

* Mention GeoJSON in the description of the useLonLat option

* Troubleshooting: unexpected long running queries
  Add remark that collection literals are inferior to FOR constructs and should not be used accidentally instead of variable names

* Add storage engine comparison table, replace hint to note that users might want to pick RocksDB for an installation

* CSS: No margin extra margin after last paragraph in callouts / hint boxes
This commit is contained in:
Simran 2017-12-08 15:40:25 +01:00 committed by Jan
parent 673ab08142
commit 7d39cf6caa
12 changed files with 128 additions and 13 deletions

View File

@ -29,6 +29,69 @@ RETURN CONCAT("foo", 123) // [ "foo123" ]
RETURN CONCAT("123", 200) // [ "123200" ]
```
Unexpected long running queries
-------------------------------
Slow queries can have various reasons and be legitimate for queries with a high
computational complexity or if they touch a lot of data. Use the *Explain*
feature to inspect execution plans and verify that appropriate indexes are
utilized. Also check for mistakes such as references to the wrong variables.
A literal collection name, which is not part of constructs like `FOR`,
`UPDATE ... IN` etc., stands for an array of all documents of that collection
and can cause an entire collection to be materialized before further
processing. It should thus be avoided.
Check the execution plan for `/* all collection documents */` and verify that
it is intended. You should also see a warning if you execute such a query:
> collection 'coll' used as expression operand
For example, instead of:
```js
RETURN coll[* LIMIT 1]
```
... with the execution plan ...
```
Execution plan:
Id NodeType Est. Comment
1 SingletonNode 1 * ROOT
2 CalculationNode 1 - LET #2 = coll /* all collection documents */[* LIMIT 0, 1] /* v8 expression */
3 ReturnNode 1 - RETURN #2
```
... you can use the following equivalent query:
```js
FOR doc IN coll
LIMIT 1
RETURN doc
```
... with the (better) execution plan:
```
Execution plan:
Id NodeType Est. Comment
1 SingletonNode 1 * ROOT
2 EnumerateCollectionNode 44 - FOR doc IN Characters /* full collection scan */
3 LimitNode 1 - LIMIT 0, 1
4 ReturnNode 1 - RETURN doc
```
Similarly, make sure you have not confused any variable names with collection
names by accident:
```js
LET names = ["John", "Mary", ...]
// supposed to refer to variable "names", not collection "Names"
FOR name IN Names
...
```
<!--
Rename to Error Sources?

View File

@ -199,6 +199,9 @@ Return whether *search* is contained in *array*. Optionally return the position.
*false* otherwise. If *returnIndex* is enabled, the position of the match is
returned (positions start at 0), or *-1* if it's not found.
To determine if or at which position a string occurs in another string, see the
[CONTAINS() string function](String.md#contains).
### PUSH()
`PUSH(anyArray, value, unique) → newArray`

View File

@ -134,8 +134,8 @@ This can be changed by setting the 3rd parameter to *true* to interpret the poin
points of the polygon
- **coord** (array): the search coordinate as a number array with two elements
- **useLonLat** (bool, *optional*): if set to *true*, the coordinates in *polygon* and
the search coordinate *coord* will be interpreted as *[lon, lat]*. The default is
*false* and the format *[lat, lon]* is expected.
the search coordinate *coord* will be interpreted as *[lon, lat]* (GeoJSON).
The default is *false* and the format *[lat, lon]* is expected.
- returns **bool** (bool): *true* if the point *coord* is inside the *polygon* or
*false* if it's not. The result is undefined (can be *true* or *false*) if the
specified point is exactly on a boundary of the polygon.

View File

@ -101,6 +101,9 @@ CONTAINS("foobarbaz", "ba", true) // 3
CONTAINS("foobarbaz", "horse", true) // -1
```
To determine if or at which position a value is included in an array, see the
[POSITION() array function](Array.md#position).
### COUNT()
This is an alias for [LENGTH()](#length).

View File

@ -12,13 +12,17 @@ There are two slightly different syntaxes for traversals in AQL, one for
### Working with named graphs
```
[WITH collection1[, collection2[, ...collectionN]]]
FOR vertex[, edge[, path]]
IN [min[..max]]
OUTBOUND|INBOUND|ANY startVertex
GRAPH graphName
[OPTIONS options]
```
- `WITH`: optional for single server instances, but required for
[graph traversals in a cluster](#graph-traversals-in-a-cluster).
- **collections** (collection, *repeatable*): list of collections that will
be involved in the traversal
- `FOR`: emits up to three variables:
- **vertex** (object): the current vertex in a traversal
- **edge** (object, *optional*): the current edge in a traversal
@ -76,6 +80,7 @@ FOR vertex[, edge[, path]]
### Working with collection sets
```
[WITH collection1[, collection2[, ...collectionN]]]
FOR vertex[, edge[, path]]
IN [min[..max]]
OUTBOUND|INBOUND|ANY startVertex
@ -113,13 +118,13 @@ collection in your traversal.
### Graph traversals in a cluster
Due to the nature of graphs, edges may reference vertices from arbitrary
collections. Following the path can thus involve documents from various
collections. Following the paths can thus involve documents from various
collections and it's not possible to predict which will be visited in a
traversal. Hence, which collections need to be locked can only be determined
at run time. Deadlocks may occur under certain circumstances.
Please consider to use the [`WITH` statement](../Operations/With.md) to
specify the collections you expect to be involved.
specify the collections you expect to be involved.
Using filters and the explainer to extrapolate the costs
--------------------------------------------------------

View File

@ -23,6 +23,10 @@ div.example_show_button {
margin-bottom: 0.85em;
}
.book .book-body .alert p:last-child {
margin-bottom: 0;
}
.columns-3 {
-webkit-column-count: 3;
-moz-column-count: 3;

View File

@ -23,6 +23,10 @@ div.example_show_button {
margin-bottom: 0.85em;
}
.book .book-body .alert p:last-child {
margin-bottom: 0;
}
.columns-3 {
-webkit-column-count: 3;
-moz-column-count: 3;

View File

@ -23,6 +23,10 @@ div.example_show_button {
margin-bottom: 0.85em;
}
.book .book-body .alert p:last-child {
margin-bottom: 0;
}
.columns-3 {
-webkit-column-count: 3;
-moz-column-count: 3;

View File

@ -51,8 +51,7 @@ Only command line options with a value should be set within the configuration
file. Command line options which act as flags should be entered on the command
line when starting the server.
Whitespace in the configuration file is ignored. Each option is specified on a
separate line in the form
Each option is specified on a separate line in the form:
```js
key = value
@ -79,6 +78,19 @@ So you see in general `--section.param value` translates to
param=value
```
{% hint 'warning' %}
Whitespace around `=` is ignored in the configuration file. Do not put spaces
around additional `=` in the parameter value however. The following example
shows the correct way to specify a log level of `trace` for the topic `startup`:
```js
log.level = startup=trace
```
Note that there is no whitespace between `startup` and `=`, and also not `=`
and `trace`.
{% endhint %}
Where one section may occur multiple times, and the last occurance of `param`
will become the final value. In case of parameters being vectors, multiple
occurance adds another item to the vector. Vectors can be identified by the
@ -104,4 +116,4 @@ or
--configuration none
```
When starting up the server. Note that, the word *none* is case-insensitive.
when starting up the server. Note that, the word *none* is case-insensitive.

View File

@ -5,21 +5,32 @@ engine. The storage engine is responsible for persisting the documents
on disk, holding copies in memory, providing indexes and caches to
speed up queries.
Up to version 3.1 ArangoDB only supported memory mapped files (MMFILES)
Up to version 3.1 ArangoDB only supported memory mapped files (MMFiles)
as sole storage engine. Beginning with 3.2 ArangoDB has support for
pluggable storage engines. The second supported engine is RocksDB from
Facebook.
| MMFiles | RocksDB |
|---|---|
| default | optional |
| dataset needs to fit into memory | work with as much data as fits on disk |
| indexes in memory | hot set in memory, data and indexes on disk |
| slow restart due to index rebuilding | fast startup (no rebuilding of indexes) |
| volatile collections (only in memory, optional) | collection data always persisted |
| collection level locking (writes block reads) | concurrent reads and writes |
*Blog article: [Comparing new RocksDB and MMFiles storage engines](https://www.arangodb.com/why-arangodb/comparing-rocksdb-mmfiles-storage-engines/)*
RocksDB is an embeddable persistent key-value store. It is a log
structure database and is optimized for fast storage.
The MMFILES engine is optimized for the use-case where the data fits
The MMFiles engine is optimized for the use-case where the data fits
into the main memory. It allows for very fast concurrent
reads. However, writes block reads and locking is on collection
level. Indexes are always in memory and are rebuilt on startup. This
gives better performance but imposes a longer startup time.
The ROCKSDB engine is optimized for large data-sets and allows for a
The RocksDB engine is optimized for large data-sets and allows for a
steady insert performance even if the data-set is much larger than the
main memory. Indexes are always stored on disk but caches are used to
speed up performance. RocksDB uses document-level locks allowing for
@ -45,7 +56,7 @@ The main advantages of RocksDB are
### Caveats
RocksDB allows concurrent writes. However, when touching the same document a
write conflict is raised. This cannot happen with the MMFILES engine, therefore
write conflict is raised. This cannot happen with the MMFiles engine, therefore
applications that switch to RocksDB need to be prepared that such exception can
arise. It is possible to exclusively lock collections when executing AQL. This
will avoid write conflicts but also inhibits concurrent writes.

View File

@ -35,7 +35,9 @@ startup parameters, installation in a cluster and so on, see
[Installing](Installing/README.md).
{% hint 'info' %}
Want help? Read more about [**consulting, training and developer support**](https://www.arangodb.com/subscriptions/)
ArangoDB offers two [**storage engines**](../Architecture/StorageEngines.md):
MMFiles and RocksDB. Choose the one which suits your needs best in the
installation process or on first startup.
{% endhint %}
### Securing the installation

View File

@ -23,6 +23,10 @@ div.example_show_button {
margin-bottom: 0.85em;
}
.book .book-body .alert p:last-child {
margin-bottom: 0;
}
.columns-3 {
-webkit-column-count: 3;
-moz-column-count: 3;