Skip to content

Commit 83c8d1a

Browse files
plumapluma
authored
Misc 3.5 changes (#617)
* Add new collection properties * Add commitIntervalMsec view property * Add primarySort view property * [WIP] Add collection.getResponsibleShard * Pass doc or shard key in getResponsibleShard * Stream transactions API proposal (#615) * Stream transactions * exec -> run "Exec" is confusing because of the similarity to "executeTransaction" (formerly "transaction"). * Explicitly clear transactions * Deprecate intermediate* opts for transactions As discussed with @jsteemann. * Make sure trx.run always returns a promise * Add test for not reverting unrelated * Docs stub * Add transaction.exists * Expand transaction documentation * Add to CHANGELOG * Implement basic analyzers API (#618) * Implement basic analyzers API * Analyzer names should always be prefixed * Add analyzer.exists * Clean up hint boxes and move View docs The View docs file should be more consistent with Collection and Graph. The hint boxes previously implied the arangojs API would be different depending on which ArangoDB version arangojs targets, which is not the case for the methdos in question. Since the views API was introduced in 3.4 it also doesn't make sense to repeat the hint box for every method on the view instance. * Add stub docs for analyzer API * Expand docs * Add example for db.analyzer * Add tests * Add to CHANGELOG * Add documentation & CHANGELOG
1 parent e90e13a commit 83c8d1a

25 files changed

+1303
-176
lines changed

‎CHANGELOG.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
77

88
## [Unreleased]
99

10+
### Changed
11+
12+
- Renamed `db.transaction` to `db.executeTransaction`
13+
14+
The method for executing server-side transactions is now called
15+
`executeTransaction` and the `params` argument now must be passed via the
16+
`options` object.
17+
18+
For backwards-compatible the new `db.transaction` method will continue to
19+
behave like before when passed an `action` string as the second argument.
20+
Note that this behavior is deprecated and will be removed in arangojs 7.
21+
22+
### Added
23+
24+
- Added support for ArangoDB 3.5 streaming transactions
25+
26+
New streaming transactions can be created using `db.beginTransaction` and
27+
existing streaming transactions can be accessed by passing the transaction ID
28+
to `db.transaction`.
29+
30+
See the documentation of the `transaction.run` method for examples of using
31+
streaming transactions with arangojs.
32+
33+
- Added support for ArangoDB 3.5 Analyzers API
34+
35+
See the documentation of the `database.analyzer` method and the `Analyzer`
36+
instances for information on using this API.
37+
38+
- Added `collection.getResponsibleShard` method
39+
40+
- Added support for new ArangoDB 3.5 collection properties
41+
42+
- Added support for new ArangoDB 3.5 view properties
43+
1044
### Fixed
1145

1246
- Fixed a problem causing empty nested AQL expressions to be converted to bind variables

‎docs/Drivers/JS/Reference/Analyzer.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Analyzer API
2+
3+
These functions implement the
4+
[HTTP API for manipulating analyzers](https://docs.arangodb.com/latest/HTTP/Analyzers.html).
5+
6+
{% hint 'info' %}
7+
Analyzers were introduced in ArangoDB 3.5 and are not supported by earlier
8+
versions of ArangoDB.
9+
{% endhint %}
10+
11+
## analyzer.exists
12+
13+
`async analyzer.exists(): boolean`
14+
15+
Checks whether the analyzer exists.
16+
17+
**Examples**
18+
19+
```js
20+
const db = new Database();
21+
const analyzer = db.analyzer("some-analyzer");
22+
const result = await analyzer.exists();
23+
// result indicates whether the analyzer exists
24+
```
25+
26+
### analyzer.get
27+
28+
`async analyzer.get(): Object`
29+
30+
Retrieves the analyzer definition for the analyzer.
31+
32+
**Examples**
33+
34+
```js
35+
const db = new Database();
36+
const analyzer = db.analyzer("some-analyzer");
37+
const definition = await analyzer.get();
38+
// definition contains the analyzer definition
39+
```
40+
41+
## analyzer.create
42+
43+
`async analyzer.create([options]): Object`
44+
45+
Creates an analyzer with the given _options_, then returns the new analyzer
46+
definition.
47+
48+
**Arguments**
49+
50+
- **options**: `Object` (optional)
51+
52+
An object with the following properties:
53+
54+
- **features**: `string` (optional)
55+
56+
The features to enable for this analyzer.
57+
58+
- **type**: `string`
59+
60+
The type of analyzer to create.
61+
Can be `"identity"`, `"delimiter"`, `"stem"`, `"norm"`, `"ngram"` or
62+
`"text"`.
63+
64+
- **properties**: `any`
65+
66+
Additional properties for the given analyzer type.
67+
68+
If the type is `"identity"`, the _properties_ are optional or can be
69+
`undefined` or `null`.
70+
71+
If the type is `"delimiter"`, the _properties_ must be an object with the
72+
following property:
73+
74+
- **delimiter**: `string`
75+
76+
Delimiter to use to split text into tokens as specified in RFC 4180,
77+
without starting new records on newlines.
78+
79+
If the type is `"stem"`, the _properties_ must be an object with the
80+
following property:
81+
82+
- **locale**: `string`
83+
84+
Text locale. Format: `language[_COUNTRY][.encoding][@variant]`.
85+
86+
If the type is `"norm"`, the _properties_ must be an object with the
87+
following properties:
88+
89+
- **locale**: `string`
90+
91+
Text locale. Format: `language[_COUNTRY][.encoding][@variant]`.
92+
93+
- **case**: `string` (Default: `"lower"`)
94+
95+
Case conversion. Can be `"lower"`, `"none"` or `"upper"`.
96+
97+
- **accent**: `boolean` (Default: `false`)
98+
99+
Preserve accent in returned words.
100+
101+
If the type is `"ngram"`, the _properties_ must be an object with the
102+
following properties:
103+
104+
- **max**: `number`
105+
106+
Maximum n-gram length.
107+
108+
- **min**: `number`
109+
110+
Minimum n-gram length.
111+
112+
- **preserveOriginal**: `boolean`
113+
114+
Output the original value as well.
115+
116+
If the type is `"text"`, the _properties_ must be an object with the
117+
following properties:
118+
119+
- **locale**: `string`
120+
121+
Text locale. Format: `language[_COUNTRY][.encoding][@variant]`.
122+
123+
- **case**: `string` (Default: `"lower"`)
124+
125+
Case conversion. Can be `"lower"`, `"none"` or `"upper"`.
126+
127+
- **stopwords**: `Array<string>` (optional)
128+
129+
Words to omit from result. Defaults to the words loaded from the file at
130+
_stopwordsPath_.
131+
132+
- **stopwordsPath**: `string` (optional)
133+
134+
Path with a `language` sub-directory containing files with words to omit.
135+
136+
Defaults to the path specified in the server-side environment variable
137+
`IRESEARCH_TEXT_STOPWORD_PATH` or the current working directory of the
138+
ArangoDB process.
139+
140+
- **accent**: `boolean` (Default: `false`)
141+
142+
Preserve accent in returned words.
143+
144+
- **stemming**: `boolean` (Default: `true`)
145+
146+
Apply stemming on returned words.
147+
148+
**Examples**
149+
150+
```js
151+
const db = new Database();
152+
const analyzer = db.analyzer("potatoes");
153+
await analyzer.create({ type: "identity" });
154+
// the identity analyzer "potatoes" now exists
155+
```
156+
157+
## analyzer.drop
158+
159+
`async analyzer.drop(): Object`
160+
161+
Deletes the analyzer from the database, then returns an object with the _name_
162+
of the analyzer that was dropped.
163+
164+
**Examples**
165+
166+
```js
167+
const db = new Database();
168+
const analyzer = db.analyzer("some-analyzer");
169+
await analyzer.drop();
170+
// the analyzer "some-analyzer" no longer exists
171+
```

‎docs/Drivers/JS/Reference/Collection/DocumentCollection.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,8 @@ Retrieves the document with the given _documentHandle_ from the collection.
2929
- **allowDirtyRead**: `boolean` (Default: `false`)
3030

3131
{% hint 'info' %}
32-
This option is only available when targeting ArangoDB 3.4 or later,
33-
see [Compatibility](../../GettingStarted/README.md#compatibility).
32+
Dirty reads were introduced in ArangoDB 3.4 and are not supported by
33+
earlier versions of ArangoDB.
3434
{% endhint %}
3535

3636
If set to `true`, the request will explicitly permit ArangoDB to return a
@@ -144,7 +144,7 @@ some elements can be error objects if the documents couldn't be saved.
144144
some network traffic.
145145

146146
- **overwrite**: `boolean` (Default: `false`)
147-
147+
148148
{% hint 'warning' %}
149149
This option is only available when targeting ArangoDB v3.4.0 and later.
150150
{% endhint %}

‎docs/Drivers/JS/Reference/Collection/EdgeCollection.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ Retrieves the edge with the given _documentHandle_ from the collection.
3131
- **allowDirtyRead**: `boolean` (Default: `false`)
3232

3333
{% hint 'info' %}
34-
This option is only available when targeting ArangoDB 3.4 or later,
35-
see [Compatibility](../../GettingStarted/README.md#compatibility).
34+
Dirty reads were introduced in ArangoDB 3.4 and are not supported by
35+
earlier versions of ArangoDB.
3636
{% endhint %}
3737

3838
If set to `true`, the request will explicitly permit ArangoDB to return a

‎docs/Drivers/JS/Reference/Collection/README.md‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Checks whether the collection exists.
2626

2727
```js
2828
const db = new Database();
29-
const collection = db.collection('some-collection');
29+
const collection = db.collection("some-collection");
3030
const result = await collection.exists();
3131
// result indicates whether the collection exists
3232
```
@@ -41,11 +41,35 @@ Retrieves general information about the collection.
4141

4242
```js
4343
const db = new Database();
44-
const collection = db.collection('some-collection');
44+
const collection = db.collection("some-collection");
4545
const data = await collection.get();
4646
// data contains general information about the collection
4747
```
4848

49+
### collection.getResponsibleShard
50+
51+
`async collection.getResponsibleShard(document): string`
52+
53+
Retrieves the `shardId` of the shard responsible for the given document.
54+
55+
**Arguments**
56+
57+
- **document**: `Object`
58+
59+
Document to look up the responsible shard for. This can either be a full
60+
document or an object with at least those attributes present, which are
61+
used as shard key for the collection (Default: `_key`).
62+
63+
**Examples**
64+
65+
```js
66+
const doc = await collection.document("abc123");
67+
const shardId = await collection.getResponsibleShard(doc);
68+
// -- or --
69+
// Assuming the collection shard key is "_key" (the default)
70+
const shardId = await collection.getResponsibleShard({ _key: "abc123" });
71+
```
72+
4973
### collection.properties
5074

5175
`async collection.properties(): Object`
@@ -56,7 +80,7 @@ Retrieves the collection's properties.
5680

5781
```js
5882
const db = new Database();
59-
const collection = db.collection('some-collection');
83+
const collection = db.collection("some-collection");
6084
const data = await collection.properties();
6185
// data contains the collection's properties
6286
```
@@ -71,7 +95,7 @@ Retrieves information about the number of documents in a collection.
7195

7296
```js
7397
const db = new Database();
74-
const collection = db.collection('some-collection');
98+
const collection = db.collection("some-collection");
7599
const data = await collection.count();
76100
// data contains the collection's count
77101
```
@@ -86,7 +110,7 @@ Retrieves statistics for a collection.
86110

87111
```js
88112
const db = new Database();
89-
const collection = db.collection('some-collection');
113+
const collection = db.collection("some-collection");
90114
const data = await collection.figures();
91115
// data contains the collection's figures
92116
```
@@ -101,7 +125,7 @@ Retrieves the collection revision ID.
101125

102126
```js
103127
const db = new Database();
104-
const collection = db.collection('some-collection');
128+
const collection = db.collection("some-collection");
105129
const data = await collection.revision();
106130
// data contains the collection's revision
107131
```
@@ -123,7 +147,7 @@ Retrieves the collection checksum.
123147

124148
```js
125149
const db = new Database();
126-
const collection = db.collection('some-collection');
150+
const collection = db.collection("some-collection");
127151
const data = await collection.checksum();
128152
// data contains the collection's checksum
129153
```

‎docs/Drivers/JS/Reference/Database/AnalyzerAccess.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Accessing analyzers
2+
3+
These functions implement the
4+
[HTTP API for accessing analyzers](https://docs.arangodb.com/latest/HTTP/Analyzers/index.html).
5+
6+
{% hint 'info' %}
7+
Analyzers were introduced in ArangoDB 3.5 and are not supported by earlier
8+
versions of ArangoDB.
9+
{% endhint %}
10+
11+
## database.analyzer
12+
13+
`database.analyzer(analyzerName): Analyzer`
14+
15+
Returns an _Analyzer_ instance representing the analyzer with the given analyzer
16+
name.
17+
18+
**Examples**
19+
20+
```js
21+
const db = new Database();
22+
const analyzer = db.analyzer("some-analyzer");
23+
const info = await analyzer.get();
24+
```
25+
26+
## database.listAnalyzers
27+
28+
`async database.listAnalyzers(): Array<Object>`
29+
30+
Fetches all analyzers visible in the database and returns an array of analyzer
31+
descriptions.
32+
33+
**Examples**
34+
35+
```js
36+
const db = new Database();
37+
const analyzers = await db.listAnalyzers();
38+
// analyzers is an array of analyzer descriptions
39+
```
40+
41+
## database.analyzers
42+
43+
`async database.analyzers(): Array<Analyzer>`
44+
45+
Fetches all analyzers visible in the database and returns an array of _Analyzer_
46+
instances for those analyzers.
47+
48+
**Examples**
49+
50+
```js
51+
const db = new Database();
52+
const analyzers = await db.analyzers();
53+
// analyzers is an array of Analyzer instances
54+
```

‎docs/Drivers/JS/Reference/Database/GraphAccess.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ const graphs = await db.listGraphs();
2828
`async database.graphs(): Array<Graph>`
2929

3030
Fetches all graphs from the database and returns an array of _Graph_ instances
31-
for the graphs.
31+
for those graphs.
3232

3333
**Examples**
3434

0 commit comments

Comments
 (0)