mirror of https://gitee.com/bigwinds/arangodb
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
Jan
parent
673ab08142
commit
7d39cf6caa
|
|
@ -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?
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
--------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue