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

Doc - Deprecation notes 3.4 (#6405) (#7033)

This commit is contained in:
Simran 2018-10-23 22:49:55 +02:00 committed by sleto-it
parent 0c6cf212e3
commit 4c9f488cbe
41 changed files with 353 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
Documentation/Books/AQL/Functions/Geo.md
View File

@ -117,9 +117,11 @@ This function can be **optimized** via a S2 based geospatial index, please look
Determine whether a coordinate is inside a polygon.
Note: the *IS_IN_POLYGON* AQL function is **deprecated** as of ArangoDB 3.4.0 in
{% hint 'warning' %}
The *IS_IN_POLYGON* AQL function is **deprecated** as of ArangoDB 3.4.0 in
favor of the new `GEO_CONTAINS` AQL function, which works with
[GeoJSON](https://tools.ietf.org/html/rfc7946) Polygons and MultiPolygons.
{% endhint %}
`IS_IN_POLYGON(polygon, latitude, longitude) → bool`
@ -279,18 +281,32 @@ Geo Index Functions
-------------------
{% hint 'warning' %}
The AQL functions `NEAR()`, `WITHIN()` and `WITHIN_RECTANGLE()` are deprecated.
The AQL functions `NEAR()`, `WITHIN()` and `WITHIN_RECTANGLE()` are
deprecated starting from version 3.4.0.
Please use the [Geo utility functions](#geo-utility-functions) instead.
{% endhint %}
AQL offers the following functions to filter data based on [geo
indexes](../../Manual/Indexing/Geo.html). These functions require the collection
AQL offers the following functions to filter data based on
[geo indexes](../../Manual/Indexing/Geo.html). These functions require the collection
to have at least one geo index. If no geo index can be found, calling this
function will fail with an error at runtime. There is no error when explaining
the query however.
### NEAR()
{% hint 'warning' %}
`NEAR` is a deprecated AQL function from version 3.4.0 on.
Use [DISTANCE()](#distance) in a query like this instead:
```js
FOR doc IN doc
SORT DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude) ASC
RETURN doc
```
Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.
{% endhint %}
`NEAR(coll, latitude, longitude, limit, distanceName) → docArray`
Return at most *limit* documents from collection *coll* that are near
@ -314,18 +330,23 @@ contain the distance value in an attribute of that name.
- returns **docArray** (array): an array of documents, sorted by distance
(shortest distance first)
### WITHIN()
**Note:** `NEAR` is a *deprecated* AQL function, instead use a query like this:
{% hint 'warning' %}
`WITHIN` is a deprecated AQL function from version 3.4.0 on.
Use [DISTANCE()](#distance) in a query like this instead:
```js
FOR doc IN doc
SORT DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude) ASC
LET d = DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude)
FILTER d <= radius
SORT d ASC
RETURN doc
```
Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.
### WITHIN()
{% endhint %}
`WITHIN(coll, latitude, longitude, radius, distanceName) → docArray`
@ -348,20 +369,21 @@ value in an attribute of that name.
- returns **docArray** (array): an array of documents, sorted by distance
(shortest distance first)
**Note:** `WITHIN` is a *deprecated* AQL function, instead use a query like this:
### WITHIN_RECTANGLE()
{% hint 'warning' %}
`WITHIN_RECTANGLE` is a deprecated AQL function from version 3.4.0 on. Use
[GEO_CONTAINS](#geocontains) and a GeoJSON polygon instead:
```js
LET rect = {type: "Polygon", coordinates: [[[longitude1, latitude1], ...]]]}
FOR doc IN doc
LET d = DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude)
FILTER d <= radius
SORT d ASC
FILTER GEO_CONTAINS(poly, [doc.longitude, doc.latitude])
RETURN doc
```
Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.
### WITHIN_RECTANGLE()
{% endhint %}
`WITHIN_RECTANGLE(coll, latitude1, longitude1, latitude2, longitude2) → docArray`
@ -379,15 +401,3 @@ bounding rectangle with the points (*latitude1*, *longitude1*) and (*latitude2*,
- **longitude2** (number): the top-right longitude portion of the search
coordinate
- returns **docArray** (array): an array of documents, in random order
**Note:** `WITHIN_RECTANGLE` is a *deprecated* AQL function, instead use a query
using a GeoJSON polygon:
```js
LET rect = {type: "Polygon", coordinates: [[[longitude1, latitude1], ...]]]}
FOR doc IN doc
FILTER GEO_CONTAINS(poly, [doc.longitude, doc.latitude])
RETURN doc
```
Assuming there exists a geo-type index on `latitude` and `longitude`, the
optimizer will recognize it and accelerate the query.

6
Documentation/Books/HTTP/SimpleQuery/README.md
View File

@ -1,6 +1,12 @@
HTTP Interface for Simple Queries
=================================
{% hint 'warning' %}
The Simple Queries API is deprecated from version 3.4.0 on.
These endpoints should no longer be used.
They are superseded by AQL queries.
{% endhint %}
Simple Queries
--------------

13
Documentation/Books/HTTP/Traversal/README.md
View File

@ -1,16 +1,19 @@
HTTP Interface for Traversals
=============================
### Traversals
{% hint 'warning' %}
The API endpoint `/_api/traversal` is deprecated from version 3.4.0 on.
The preferred way to traverse graphs is with AQL.
{% endhint %}
ArangoDB's graph traversals are executed on the server. Traversals can be
initiated by clients by sending the traversal description for execution to
the server.
Traversals in ArangoDB are used to walk over a graph
stored in one [edge collection](../../Manual/Appendix/Glossary.html#edge-collection). It can easily be described
which edges of the graph should be followed and which actions
should be performed on each visited vertex.
Traversals in ArangoDB are used to walk over a graph stored in one
[edge collection](../../Manual/Appendix/Glossary.html#edge-collection).
It can easily be described which edges of the graph should be followed
and which actions should be performed on each visited vertex.
Furthermore the ordering of visiting the nodes can be
specified, for instance depth-first or breadth-first search
are offered.

5
Documentation/Books/Manual/Foxx/Guides/LegacyMode.md
View File

@ -5,11 +5,12 @@ ArangoDB 3 continues to support Foxx services written for ArangoDB 2.8 by
running them in a special legacy compatibility mode that provides access to
some of the modules and APIs no longer provided in 3.0 and beyond.
{% hint 'info' %}
{% hint 'warning' %}
Legacy compatibility mode is strictly intended as a temporary stop
gap solution for supporting existing services while
[upgrading to ArangoDB 3.x](../Migrating2x/README.md)
and should not be considered a permanent feature of ArangoDB or Foxx.
and is not a permanent feature of ArangoDB or Foxx. It is considered
as deprecated from v3.4.0 on.
{% endhint %}
In order to mark an existing service as a legacy service,

5
Documentation/Books/Manual/Indexing/Persistent.md
View File

@ -1,6 +1,11 @@
Persistent indexes
==================
{% hint 'warning' %}
The persistent index type is considered as deprecated from version 3.4.0 on.
It will be removed in 4.0.0. If you use the RocksDB storage engine, you can
replace it with a skiplist index, which uses the same implementation.
{% endhint %}
Introduction to Persistent Indexes
----------------------------------

14
Documentation/Books/Manual/ReleaseNotes/UpgradingChanges34.md
View File

@ -365,8 +365,8 @@ The following APIs have been added or augmented:
The old/new revisions can be accessed by passing the URL parameters `returnOld` and
`returnNew` to the following endpoints:
* /_api/gharial/<graph>/vertex/<collection>
* /_api/gharial/<graph>/edge/<collection>
* `/_api/gharial/<graph>/vertex/<collection>`
* `/_api/gharial/<graph>/edge/<collection>`
The exception from this is that the HTTP DELETE verb for these APIs does not
support `returnOld` because that would make the existing API incompatible.
@ -456,7 +456,7 @@ instead of error 1582 (`ERROR_QUERY_FUNCTION_NOT_FOUND`) in some situations.
now always produce the same result, whereas in previous versions of ArangoDB the
function may have generated different results.
Each AQL query that is run will still evalute the result value of the `DATE_NOW`
Each AQL query that is run will still evaluate the result value of the `DATE_NOW`
function independently, but only once at the beginning of the query. This is most
often what is desired anyway, but the change makes `DATE_NOW` useless to measure
time differences inside a single query.
@ -720,7 +720,7 @@ removed in future versions of ArangoDB:
using the simple query API, because that is more flexible and allows greater
control of how the queries are executed.
* the REST API for querying endpoints at `/_api/endpoints`:
* the REST API for querying endpoints at `/_api/endpoint`:
The API `/_api/endpoint` is deprecated since ArangoDB version 3.1.
For cluster mode there is `/_api/cluster/endpoints` to find all current
@ -759,6 +759,12 @@ removed in future versions of ArangoDB:
The types `geo1` and `geo2` will still work in ArangoDB 3.4, but may be removed
in future versions.
* the persistent index type is marked for removal in 4.0.0 and is thus deprecated.
This index type was added when there was only the MMFiles storage engine as
kind of a stop gap. We recommend to switch to RocksDB engine, which persists
all index types with no difference between skiplist and persistent indexes.
* the legacy mode for Foxx applications from ArangoDB 2.8 or earlier:
The legacy mode is described in more detail in the [Foxx manual](https://docs.arangodb.com/3.3/Manual/Foxx/LegacyMode.html).

8
Documentation/DocuBlocks/Rest/Administration/get_api_endpoint.md
View File

@ -4,9 +4,13 @@
@RESTHEADER{GET /_api/endpoint, Return list of all endpoints}
@RESTDESCRIPTION
*THIS API IS DEPRECATED*
@HINTS
{% hint 'warning' %}
This route should no longer be used.
It is considered as deprecated from version 3.4.0 on.
{% endhint %}
@RESTDESCRIPTION
Returns an array of all configured endpoints the server is listening on.
The result is a JSON array of JSON objects, each with `"entrypoint"' as

6
Documentation/DocuBlocks/Rest/Collections/delete_api_collection.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{DELETE /_api/collection/{collection-name}, Drops a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collection_checksum.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection/{collection-name}/checksum, Return checksum for the collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collection_count.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection/{collection-name}/count, Return number of documents in a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collection_figures.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection/{collection-name}/figures, Return statistics for a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collection_name.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection/{collection-name}, Return information about a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collection_properties.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection/{collection-name}/properties, Read properties of a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collection_revision.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection/{collection-name}/revision, Return collection revision id}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/get_api_collections.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/collection,reads all collections}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTQUERYPARAMETERS
@RESTQUERYPARAM{excludeSystem,boolean,optional}

6
Documentation/DocuBlocks/Rest/Collections/post_api_collection.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{POST /_api/collection, Create collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTDESCRIPTION
Creates a new collection with a given name. The request must contain an
object with the following attributes.

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_load.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/load, Load collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_load_indexes_in_memory.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/loadIndexesIntoMemory, Load Indexes into Memory}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_properties.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/properties, Change properties of a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_rename.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/rename, Rename collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_rotate.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/rotate, Rotate journal of a collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_truncate.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/truncate, Truncate collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

6
Documentation/DocuBlocks/Rest/Collections/put_api_collection_unload.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{PUT /_api/collection/{collection-name}/unload, Unload collection}
@HINTS
{% hint 'warning' %}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
{% endhint %}
@RESTURLPARAMETERS
@RESTURLPARAM{collection-name,string,required}

7
Documentation/DocuBlocks/Rest/Graph Traversal/HTTP_API_TRAVERSAL.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{POST /_api/traversal,executes a traversal}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
It is considered as deprecated from version 3.4.0 on.
It is superseded by AQL graph traversal.
{% endhint %}
@RESTDESCRIPTION
Starts a traversal starting from a given vertex and following.
edges contained in a given edgeCollection. The request must

6
Documentation/DocuBlocks/Rest/Replication/get_api_replication_logger_follow.md
View File

@ -4,6 +4,12 @@
@RESTHEADER{GET /_api/replication/logger-follow, Returns log entries}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
It is considered as deprecated from version 3.4.0 on.
{% endhint %}
@RESTQUERYPARAMETERS
@RESTQUERYPARAM{from,number,optional}

11
Documentation/DocuBlocks/Rest/Simple Queries/RestLookupByKeys.md
View File

@ -3,6 +3,13 @@
@RESTHEADER{PUT /_api/simple/lookup-by-keys, Find documents by their keys}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to look in for the documents
@ -17,6 +24,10 @@ will be returned. Keys for which no document can be found in the
underlying collection are ignored, and no exception will be thrown for
them.
Equivalent AQL query:
FOR doc IN @@collection FILTER doc._key IN @keys RETURN doc
The body of the response contains a JSON object with a *documents*
attribute. The *documents* attribute is an array containing the
matching documents. The order in which matching documents are present

12
Documentation/DocuBlocks/Rest/Simple Queries/RestRemoveByKeys.md
View File

@ -3,6 +3,13 @@
@RESTHEADER{PUT /_api/simple/remove-by-keys, Remove documents by their keys}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to look in for the documents to remove
@ -35,6 +42,11 @@ contained in the *keys* array. Keys for which no document can be found in
the underlying collection are ignored, and no exception will be thrown for
them.
Equivalent AQL query (the RETURN clause is optional):
FOR key IN @keys REMOVE key IN @@collection
RETURN OLD
The body of the response contains a JSON object with information how many
documents were removed (and how many were not). The *removed* attribute will
contain the number of actually removed documents. The *ignored* attribute

7
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_all.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/all, Return all documents}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTALLBODYPARAM{query,string,required}
Contains the query.

9
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_any.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/any, Return a random document}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTDESCRIPTION
Returns a random document from a collection. The call expects a JSON object
as body with the following attributes:
@ -13,7 +20,7 @@ The identifier or name of the collection to query.
Returns a JSON object with the document stored in the attribute
*document* if the collection contains at least one document. If
the collection is empty, the *document* attrbute contains null.
the collection is empty, the *document* attribute contains null.
@RESTRETURNCODES

14
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_by_example.md
View File

@ -4,6 +4,20 @@
@RESTHEADER{PUT /_api/simple/by-example, Simple query by-example}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
{% hint 'warning' %}
Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive.
A more lightweight alternative is to use the [HTTP Cursor API](../AqlQueryCursor/README.md).
Starting from versions 3.2.14 and 3.3.8 this performance impact is not
an issue anymore, as the internal implementation of the API has changed.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.

14
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_first_example.md
View File

@ -4,6 +4,20 @@
@RESTHEADER{PUT /_api/simple/first-example, Find documents matching an example}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
{% hint 'warning' %}
Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive.
A more lightweight alternative is to use the [HTTP Cursor API](../AqlQueryCursor/README.md).
Starting from versions 3.2.14 and 3.3.8 this performance impact is not
an issue anymore, as the internal implementation of the API has changed.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.

8
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_fulltext.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/fulltext, Fulltext index query}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.
@ -40,7 +47,6 @@ way for retrieving documents from a collection using the near operator is
to issue an AQL query using the *FULLTEXT* [AQL function](../../AQL/Functions/Fulltext.html)
as follows:
FOR doc IN FULLTEXT(@@collection, @attributeName, @queryString, @limit)
RETURN doc

8
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_near.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/near, Returns documents near a coordinate}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.
@ -47,7 +54,6 @@ This API may be removed in future versions of ArangoDB. The preferred
way for retrieving documents from a collection using the near operator is
to issue an [AQL query](../../AQL/Functions/Geo.html) using the *NEAR* function as follows:
FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit)
RETURN doc`

8
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_range.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/range, Simple range query}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.
@ -39,7 +46,6 @@ The function may be removed in future versions of ArangoDB. The preferred
way for retrieving documents from a collection within a specific range
is to use an AQL query as follows:
FOR doc IN @@collection
FILTER doc.value >= @left && doc.value < @right
LIMIT @skip, @limit

7
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_remove_by_example.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/remove-by-example, Remove documents by example}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to remove from.

7
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_replace_by_example.md
View File

@ -3,6 +3,13 @@
@RESTHEADER{PUT /_api/simple/replace-by-example, Replace documents by example}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to replace within.

8
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_update_by_example.md
View File

@ -3,6 +3,13 @@
@RESTHEADER{PUT /_api/simple/update-by-example, Update documents by example}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to update within.
@ -51,7 +58,6 @@ Using it will result in an error.
Returns the number of documents that were updated.
@RESTRETURNCODES
@RESTRETURNCODE{200}

8
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_within.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/within, Find documents within a radius around a coordinate}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.
@ -48,7 +55,6 @@ This API may be removed in future versions of ArangoDB. The preferred
way for retrieving documents from a collection using the near operator is
to issue an [AQL query](../../AQL/Functions/Geo.html) using the *WITHIN* function as follows:
FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName)
RETURN doc

7
Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_within_rectangle.md
View File

@ -4,6 +4,13 @@
@RESTHEADER{PUT /_api/simple/within-rectangle, Within rectangle query}
@HINTS
{% hint 'warning' %}
This route should no longer be used.
All endpoints for Simple Queries are deprecated from version 3.4.0 on.
They are superseded by AQL queries.
{% endhint %}
@RESTBODYPARAM{collection,string,required,string}
The name of the collection to query.

12
Documentation/Scripts/generateMdFiles.py
View File

@ -147,12 +147,14 @@ def getRestBodyParam():
def getRestDescription():
#print >>sys.stderr, "RESTDESCRIPTION"
if thisVerb['description']:
#print >> sys.stderr, thisVerb['description']
return RX3[0].sub(RX3[1], thisVerb['description'])
description = thisVerb['description']
#print >> sys.stderr, description
description = RX4[0].sub(RX4[1], description)
return RX3[0].sub(RX3[1], description)
else:
#print >> sys.stderr, "ELSE"
return ""
def getRestReplyBodyParam(param):
rc = "\n**Response Body**\n"
@ -214,6 +216,7 @@ SIMPL_REPL_VALIDATE_DICT = {
}
SIMPL_REPL_DICT = {
"\\" : "\\\\",
"@HINTS" : "",
"@RESTDESCRIPTION" : getRestDescription,
"@RESTURLPARAMETERS" : "\n**Path Parameters**\n",
"@RESTQUERYPARAMETERS" : "\n**Query Parameters**\n",
@ -236,6 +239,7 @@ SIMPLE_RX = re.compile(
r'''
\\| # the backslash...
@RESTDESCRIPTION| # -> <empty>
@HINTS| # -> <inject hints>
@RESTURLPARAMETERS| # -> \n**Path Parameters**\n
@RESTQUERYPARAMETERS| # -> \n**Query Parameters**\n
@RESTHEADERPARAMETERS| # -> \n**Header Parameters**\n
@ -338,6 +342,8 @@ RX2 = [
RX3 = (re.compile(r'\*\*Example:\*\*((?:.|\n)*?)</code></pre>'), r"")
RX4 = (re.compile(r'<!-- Hints Start -->.*<!-- Hints End -->', re.DOTALL), r"")
match_RESTHEADER = re.compile(r"@RESTHEADER\{(.*)\}")
match_RESTRETURNCODE = re.compile(r"@RESTRETURNCODE\{(.*)\}")
have_RESTBODYPARAM = re.compile(r"@RESTBODYPARAM|@RESTDESCRIPTION")

43
utils/generateSwagger.py
View File

@ -301,7 +301,7 @@ def Typography(txt):
r = rc(r"""@ref [a-zA-Z0-9]+""", MS)
txt = r.sub("the manual", txt)
txt = re.sub(r"@endDocuBlock", "", txt)
txt = BACKSLASH(txt);
txt = BACKSLASH(txt)
return txt
################################################################################
@ -373,6 +373,7 @@ class Regexen:
self.DESCRIPTION_BL = re.compile('^\s*$')
self.EMPTY_LINE = re.compile('^\s*$')
self.START_DOCUBLOCK = re.compile('.*@startDocuBlock ')
self.HINTS = re.compile('.*@HINTS')
self.END_EXAMPLE_ARANGOSH_RUN = re.compile('.*@END_EXAMPLE_ARANGOSH_RUN')
self.EXAMPLES = re.compile('.*@EXAMPLES')
self.EXAMPLE_ARANGOSH_RUN = re.compile('.*@EXAMPLE_ARANGOSH_RUN{')
@ -412,6 +413,7 @@ def next_step(fp, line, r):
if not line: return eof, (fp, line)
elif check_end_of_comment(line, r): return skip_code, (fp, line)
elif r.START_DOCUBLOCK.match(line): return start_docublock, (fp, line)
elif r.HINTS.match(line): return hints, (fp, line)
elif r.EXAMPLE_ARANGOSH_RUN.match(line): return example_arangosh_run, (fp, line)
elif r.RESTBODYPARAM.match(line): return restbodyparam, (fp, line)
elif r.RESTSTRUCT.match(line): return reststruct, (fp, line)
@ -571,6 +573,7 @@ def restheader(cargo, r=Regexen()):
swagger['paths'][httpPath][method] = {
'x-filename': fn,
'x-hints': '',
'x-examples': [],
'tags': [currentTag],
'summary': summary.strip(),
@ -879,6 +882,23 @@ def restqueryparam(cargo, r=Regexen()):
swagger['paths'][httpPath][method]['parameters'].append(para)
return generic_handler_desc(cargo, r, "restqueryparam", None, para, 'description')
################################################################################
### @brief hints
################################################################################
def hints(cargo, r=Regexen()):
global swagger, operation, httpPath, method
ret = generic_handler_desc(cargo, r, "hints", None,
swagger['paths'][httpPath][method], 'x-hints')
if r.TRIPLENEWLINEATSTART.match(swagger['paths'][httpPath][method]['x-hints']):
(fp, last) = cargo
print >> sys.stderr, 'remove newline after @HINTS in file %s' % (fp.name)
exit(1)
return ret
################################################################################
### @brief restdescription
################################################################################
@ -888,8 +908,8 @@ def restdescription(cargo, r=Regexen()):
swagger['paths'][httpPath][method]['description'] += '\n\n'
ret = generic_handler_desc(cargo, r, "restdescription", None,
swagger['paths'][httpPath][method],
'description')
swagger['paths'][httpPath][method],
'description')
if r.TRIPLENEWLINEATSTART.match(swagger['paths'][httpPath][method]['description']):
(fp, last) = cargo
@ -1164,6 +1184,7 @@ automat.add_state(comment)
automat.add_state(eof, end_state=1)
automat.add_state(error, end_state=1)
automat.add_state(start_docublock)
automat.add_state(hints)
automat.add_state(example_arangosh_run)
automat.add_state(examples)
automat.add_state(skip_code)
@ -1313,7 +1334,7 @@ for version in f:
f.close()
paths = {};
paths = {}
topdir = sys.argv[4]
files = {}
@ -1355,7 +1376,7 @@ def descOffsetGet(value):
for route in swagger['paths'].keys():
for verb in swagger['paths'][route].keys():
offsetPlus = 0;
offsetPlus = 0
thisVerb = swagger['paths'][route][verb]
if len(thisVerb['description']) == 0:
print >> sys.stderr, "Description of Route empty; @RESTDESCRIPTION missing?"
@ -1427,6 +1448,18 @@ for route in swagger['paths'].keys():
#print '-'*80
#print thisVerb['description']
# Simplify hint box code to something that works in Swagger UI
# Append the result to the description field
# Place invisible markers, so that hints can be removed again
if 'x-hints' in thisVerb and len(thisVerb['x-hints']) > 0:
thisVerb['description'] += '\n<!-- Hints Start -->'
tmp = re.sub("{% hint '([^']+?)' %}",
lambda match: "\n\n**{}:** ".format(match.group(1).title()),
thisVerb['x-hints'])
tmp = re.sub('{%[^%]*?%}', '', tmp)
thisVerb['description'] += tmp
thisVerb['description'] += '\n<!-- Hints End -->'
# Append the examples to the description:
if 'x-examples' in thisVerb and len(thisVerb['x-examples']) > 0:
thisVerb['description'] += '\n'