8000 Add documentation about options used in database creation (#243) · arangodb/docs@5ff4726 · GitHub
[go: up one dir, main page]
Skip to content
This repository was archived by the owner on Dec 13, 2023. It is now read-only.

Commit 5ff4726

Browse files
ObiWahnSimran-B
ObiWahn
authored and
Simran-B
committed
Add documentation about options used in database creation (#243)
Moreover, document db._properties() / db._queryProperties()
1 parent 64aa377 commit 5ff4726

6 files changed

+130
-69
lines changed

‎3.5/appendix-references-dbobject.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ The following methods exists on the *_db* object:
3030
* [db._isSystem()](data-modeling-databases-working-with.html#issystem)
3131
* [db._name()](data-modeling-databases-working-with.html#name)
3232
* [db._path()](data-modeling-databases-working-with.html#path)
33-
* [db._version()](data-modeling-documents-document-methods.html#get-the-version-of-arangodb)
33+
* [db._queryProperties()](data-modeling-databases-working-with.html#properties)
3434

3535
*Collection*
3636

@@ -67,3 +67,4 @@ The following methods exists on the *_db* object:
6767
* [db._engine()](data-modeling-databases-working-with.html#engine)
6868
* [db._engineStats()](data-modeling-databases-working-with.html#engine-statistics)
6969
* [db._executeTransaction()](transactions-transaction-invocation.html)
70+
* [db._version()](data-modeling-databases-working-with.html#get-the-version-of-arangodb)

‎3.5/data-modeling-databases-working-with.md

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,31 @@ database management operations such as create or drop can only be executed
8888
from within this database. Additionally, the *_system* database itself
8989
cannot be dropped.
9090

91+
### Properties
92+
93+
<!-- arangod/V8Server/v8-vocbase.cpp -->
94+
95+
return the path to database files
96+
`db._queryProperties()`
97+
98+
Returns the properties of the current database as an object with the following
99+
attributes:
100+
101+
- *id*: the database id
102+
- *name*: the database name
103+
- *isSystem*: the database type
104+
- *path*: the path to database files
105+
106+
**Examples**
107+
108+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
109+
@startDocuBlockInline dbProperties
110+
@EXAMPLE_ARANGOSH_OUTPUT{dbProperties}
111+
require("@arangodb").db._queryProperties();
112+
@END_EXAMPLE_ARANGOSH_OUTPUT
113+
@endDocuBlock dbProperties
114+
{% endarangoshexample %}
115+
{% include arangoshexample.html id=examplevar script=script result=result %}
91116

92117
### Use Database
93118
<!-- arangod/V8Server/v8-vocbase.cpp -->
@@ -203,10 +228,29 @@ as a list of supported features (types of indexes and
203228

204229
### Engine statistics
205230

206-
retrieve statistics related to the storage engine (rocksdb)
231+
retrieve statistics related to the storage engine (RocksDB)
207232
`db._engineStats()`
208233

209234
Returns some statistics related to the storage engine activity, including figures
210235
about data size, cache usage, etc.
211236

212237
**Note**: Currently this only produces useful output for the RocksDB engine.
238+
239+
Get the Version of ArangoDB
240+
---------------------------
241+
242+
`db._version()`
243+
244+
Returns the server version string. Note that this is not the version of the
245+
database.
246+
247+
**Examples**
248+
249+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
250+
@startDocuBlockInline dbVersion
251+
@EXAMPLE_ARANGOSH_OUTPUT{dbVersion}
252+
require("@arangodb").db._version();
253+
@END_EXAMPLE_ARANGOSH_OUTPUT
254+
@endDocuBlock dbVersion
255+
{% endarangoshexample %}
256+
{% include arangoshexample.html id=examplevar script=script result=result %}

‎3.5/data-modeling-documents-document-methods.md

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1255,25 +1255,6 @@ Throws if the document key is invalid. Note that this method does not
12551255
check whether the document already exists in this collection.
12561256

12571257

1258-
Get the Version of ArangoDB
1259-
---------------------------
1260-
1261-
`db._version()`
1262-
1263-
Returns the server version string. Note that this is not the version of the
1264-
database.
1265-
1266-
1267-
**Examples**
1268-
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
1269-
1270-
@startDocuBlockInline dbVersion
1271-
@EXAMPLE_ARANGOSH_OUTPUT{dbVersion}
1272-
require("@arangodb").db._version();
1273-
@END_EXAMPLE_ARANGOSH_OUTPUT
1274-
@endDocuBlock dbVersion
1275-
{% endarangoshexample %}
1276-
{% include arangoshexample.html id=examplevar script=script result=result %}
12771258
Edges
12781259
-----
12791260

‎3.6/appendix-references-dbobject.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ The following methods exists on the *_db* object:
3030
* [db._isSystem()](data-modeling-databases-working-with.html#issystem)
3131
* [db._name()](data-modeling-databases-working-with.html#name)
3232
* [db._path()](data-modeling-databases-working-with.html#path)
33-
* [db._version()](data-modeling-documents-document-methods.html#get-the-version-of-arangodb)
33+
* [db._properties()](data-modeling-databases-working-with.html#properties)
3434

3535
*Collection*
3636

@@ -67,3 +67,4 @@ The following methods exists on the *_db* object:
6767
* [db._engine()](data-modeling-databases-working-with.html#engine)
6868
* [db._engineStats()](data-modeling-databases-working-with.html#engine-statistics)
6969
* [db._executeTransaction()](transactions-transaction-invocation.html)
70+
* [db._version()](data-modeling-databases-working-with.html#get-the-version-of-arangodb)

‎3.6/data-modeling-databases-working-with.md

Lines changed: 81 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,17 @@ Please note that several of these methods can be used from the _system
1313
database only.
1414

1515
### Name
16-
<!-- arangod/V8Server/v8-vocbase.cpp -->
1716

17+
<!-- arangod/V8Server/v8-vocbase.cpp -->
1818

1919
return the database name
2020
`db._name()`
2121

2222
Returns the name of the current database as a string.
2323

24-
2524
**Examples**
26-
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
2725

26+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
2827
@startDocuBlockInline dbName
2928
@EXAMPLE_ARANGOSH_OUTPUT{dbName}
3029
require("@arangodb").db._name();
@@ -34,18 +33,17 @@ Returns the name of the current database as a string.
3433
{% include arangoshexample.html id=examplevar script=script result=result %}
3534

3635
### ID
37-
<!-- arangod/V8Server/v8-vocbase.cpp -->
3836

37+
<!-- arangod/V8Server/v8-vocbase.cpp -->
3938

4039
return the database id
4140
`db._id()`
4241

4342
Returns the id of the current database as a string.
4443

45-
4644
**Examples**
47-
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
4845

46+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
4947
@startDocuBlockInline dbId
5048
@EXAMPLE_ARANGOSH_OUTPUT{dbId}
5149
require("@arangodb").db._id();
@@ -55,18 +53,17 @@ Returns the id of the current database as a string.
5553
{% include arangoshexample.html id=examplevar script=script result=result %}
5654

5755
### Path
58-
<!-- arangod/V8Server/v8-vocbase.cpp -->
5956

57+
<!-- arangod/V8Server/v8-vocbase.cpp -->
6058

6159
return the path to database files
6260
`db._path()`
6361

6462
Returns the filesystem path of the current database as a string.
6563

66-
6764
**Examples**
68-
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
6965

66+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
7067
@startDocuBlockInline dbPath
7168
@EXAMPLE_ARANGOSH_OUTPUT{dbPath}
7269
require("@arangodb").db._path();
@@ -76,8 +73,8 @@ Returns the filesystem path of the current database as a string.
7673
{% include arangoshexample.html id=examplevar script=script result=result %}
7774

7875
### isSystem
79-
<!-- arangod/V8Server/v8-vocbase.cpp -->
8076

77+
<!-- arangod/V8Server/v8-vocbase.cpp -->
8178

8279
return the database type
8380
`db._isSystem()`
@@ -88,10 +85,40 @@ database management operations such as create or drop can only be executed
8885
from within this database. Additionally, the *_system* database itself
8986
cannot be dropped.
9087

88+
### Properties
9189

92-
### Use Database
9390
<!-- arangod/V8Server/v8-vocbase.cpp -->
9491

92+
return the path to database files
93+
`db._properties()`
94+
95+
Returns the properties of the current database as an object with the following
96+
attributes:
97+
98+
- *id*: the database id
99+
- *name*: the database name
100+
- *isSystem*: the database type
101+
- *path*: the path to database files
102+
- *sharding*: the sharding method to use for new collections *(Cluster only)*
103+
- *replicationFactor*: default replication factor for new collections
104+
*(Cluster only)*
105+
- *writeConcern*: a shard will refuse to write if less than this amount
106+
of copies are in sync *(Cluster only)*
107+
108+
**Examples**
109+
110+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
111+
@startDocuBlockInline dbProperties_cluster
112+
@EXAMPLE_ARANGOSH_OUTPUT{dbProperties_cluster}
113+
require("@arangodb").db._properties();
114+
@END_EXAMPLE_ARANGOSH_OUTPUT
115+
@endDocuBlock dbProperties_cluster
116+
{% endarangoshexample %}
117+
{% include arangoshexample.html id=examplevar script=script result=result %}
118+
119+
### Use Database
120+
121+
<!-- arangod/V8Server/v8-vocbase.cpp -->
95122

96123
change the current database
97124
`db._useDatabase(name)`
@@ -110,21 +137,19 @@ database might not work, and the connection / session should be closed and
110137
restarted with different username and password credentials and/or
111138
endpoint data.
112139

113-
114140
### List Databases
115-
<!-- arangod/V8Server/v8-vocbase.cpp -->
116141

142+
<!-- arangod/V8Server/v8-vocbase.cpp -->
117143

118144
return the list of all existing databases
119145
`db._databases()`
120146

121147
Returns the list of all databases. This method can only be used from within
122148
the *_system* database.
123149

124-
125150
### Create Database
126-
<!-- arangod/V8Server/v8-vocbase.cpp -->
127151

152+
<!-- arangod/V8Server/v8-vocbase.cpp -->
128153

129154
create a new database
130155
`db._createDatabase(name, options, users)`
@@ -138,19 +163,29 @@ change into the current database to the new database. Changing the current
138163
database must explicitly be requested by using the
139164
*db._useDatabase* method.
140165

141-
The *options* attribute currently has no meaning and is reserved for
142-
future use.
166+
The *options* attribute can be used to set defaults for collections that will
167+
be created in the new database:
168+
169+
- *sharding*: The sharding method to use. Valid values are: `""` or `"single"`.
170+
Setting this option to `"single"` will enable the OneShard feature in the
171+
Enterprise Edition.
172+
- *replicationFactor*: Default replication factor. Special values include
173+
`"satellite"`, which will replicate the collection to every DBServer, and
174+
`1`, which disables replication.
175+
- *minReplicationFactor*: Default minimum replication factor. If there are
176+
less than minReplication replicas available the collection will become
177+
read-only.
143178

144179
The optional *users* attribute can be used to create initial users for
145180
the new database. If specified, it must be a list of user objects. Each user
146181
object can contain the following attributes:
147182

148-
* *username*: the user name as a string. This attribute is mandatory.
149-
* *passwd*: the user password as a string. If not specified, then it defaults
183+
- *username*: the user name as a string. This attribute is mandatory.
184+
- *passwd*: the user password as a string. If not specified, then it defaults
150185
to an empty string.
151-
* *active*: a boolean flag indicating whether the user account should be
186+
- *active*: a boolean flag indicating whether the user account should be
152187
active or not. The default value is *true*.
153-
* *extra*: an optional JSON object with extra user information. The data
188+
- *extra*: an optional JSON object with extra user information. The data
154189
contained in *extra* will be stored for the user but not be interpreted
155190
further by ArangoDB.
156191

@@ -163,22 +198,21 @@ into the new database (username and password must be identical to the current
163198
session) and add or modify users with the following commands.
164199

165200
```js
166-
require("@arangodb/users").save(username, password, true);
167-
require("@arangodb/users").update(username, password, true);
168-
require("@arangodb/users").remove(username);
201+
require("@arangodb/users").save(username, password, true);
202+
require("@arangodb/users").update(username, password, true);
203+
require("@arangodb/users").remove(username);
169204
```
170205
Alternatively, you can specify user data directly. For example:
171206

172207
```js
173-
db._createDatabase("newDB", {}, [{ username: "newUser", passwd: "123456", active: true}])
208+
db._createDatabase("newDB", {}, [{ username: "newUser", passwd: "123456", active: true}])
174209
```
175210

176211
Those methods can only be used from within the *_system* database.
177212

178-
179213
### Drop Database
180-
<!-- arangod/V8Server/v8-vocbase.cpp -->
181214

215+
<!-- arangod/V8Server/v8-vocbase.cpp -->
182216

183217
drop an existing database
184218
`db._dropDatabase(name)`
@@ -203,10 +237,29 @@ as a list of supported features (types of indexes and
203237

204238
### Engine statistics
205239

206-
retrieve statistics related to the storage engine (rocksdb)
240+
retrieve statistics related to the storage engine (RocksDB)
207241
`db._engineStats()`
208242

209243
Returns some statistics related to the storage engine activity, including figures
210244
about data size, cache usage, etc.
211245

212246
**Note**: Currently this only produces useful output for the RocksDB engine.
247+
248+
Get the Version of ArangoDB
249+
---------------------------
250+
251+
`db._version()`
252+
253+
Returns the server version string. Note that this is not the version of the
254+
database.
255+
256+
**Examples**
257+
258+
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
259+
@startDocuBlockInline dbVersion
260+
@EXAMPLE_ARANGOSH_OUTPUT{dbVersion}
261+
require("@arangodb").db._version();
262+
@END_EXAMPLE_ARANGOSH_OUTPUT
263+
@endDocuBlock dbVersion
264+
{% endarangoshexample %}
265+
{% include arangoshexample.html id=examplevar script=script result=result %}

‎3.6/data-modeling-documents-document-methods.md

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1255,25 +1255,6 @@ Throws if the document key is invalid. Note that this method does not
12551255
check whether the document already exists in this collection.
12561256

12571257

1258-
Get the Version of ArangoDB
1259-
---------------------------
1260-
1261-
`db._version()`
1262-
1263-
Returns the server version string. Note that this is not the version of the
1264-
database.
1265-
1266-
1267-
**Examples**
1268-
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
1269-
1270-
@startDocuBlockInline dbVersion
1271-
@EXAMPLE_ARANGOSH_OUTPUT{dbVersion}
1272-
require("@arangodb").db._version();
1273-
@END_EXAMPLE_ARANGOSH_OUTPUT
1274-
@endDocuBlock dbVersion
1275-
{% endarangoshexample %}
1276-
{% include arangoshexample.html id=examplevar script=script result=result %}
12771258
Edges
12781259
-----
12791260

0 commit comments

Comments
 (0)
0