From 3568489a44ff74fc6d662a008441997950ac5cc1 Mon Sep 17 00:00:00 2001
From: tb06904 <141412860+tb06904@users.noreply.github.com>
Date: Thu, 2 May 2024 14:28:44 +0000
Subject: [PATCH] update gremlin docs with current features

---
 .../query/gremlin/gremlin-limits.md           | 18 ++++++++----------
 docs/user-guide/query/gremlin/gremlin.md      | 19 +++++++++++++++++++
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/docs/user-guide/query/gremlin/gremlin-limits.md b/docs/user-guide/query/gremlin/gremlin-limits.md
index f16fd86046..1edf225f37 100644
--- a/docs/user-guide/query/gremlin/gremlin-limits.md
+++ b/docs/user-guide/query/gremlin/gremlin-limits.md
@@ -6,28 +6,26 @@ but some features may also be yet to be implemented.
 
 Current TinkerPop features not present in the GafferPop implementation:
 
-- Property index for allowing unseeded queries.
-- Using a Gaffer user for authentication. Access control and authorisations are not supported
-as these are based on users.
-- Removal of entities/edges or properties - base Gaffer currently does not
+- Property index for allowing unseeded queries (unseeded queries run a `GetAllElements`).
+- Gaffer graphs are readonly to Gremlin queries.
   support this.
 - TinkerPop Graph Computer is not supported.
-- Graph Variables can't be updated - there is limited support for this in base
-  Gaffer as usually requires shutting down and restarting the Graph.
 - TinkerPop Transactions are not supported.
+- TinkerPop Lambdas are not supported.
 
 Current known limitations or bugs:
 
+- Proper user authentication is only available if using a Gremlin server to
+  connect to the graph.
+- Performance compared to standard Gaffer `OperationChain`s will likely be
+  slower as multiple Gaffer `Operations` may utilised to perform one Gremlin
+  step.
 - The entity group `id` is reserved for an empty group containing only the
   vertex ID, this is currently used as a workaround for other limitations.
 - When you get the in or out Vertex directly off an Edge it will not contain any
   actual properties or be in correct group/label - it just returns a vertex in
   the `id` group. This is due to Gaffer allowing multiple entities to be
   associated with the source and destination vertices of an Edge.
-- Limited support for updating properties, this has partial support via Gaffer's
-  ingest aggregation mechanism.
-- Performance compared to standard Gaffer OperationChains is hampered due to
-  a custom `TraversalStratergy` not being implemented.
 - The ID of an Edge follows a specific format that is made up of its source and
   destination IDs like `[source, dest]`. To use this in a seeded query you must
   format it like `g.E("[source, dest]")` or a list like
diff --git a/docs/user-guide/query/gremlin/gremlin.md b/docs/user-guide/query/gremlin/gremlin.md
index 60e71bf591..cf8a43de7e 100644
--- a/docs/user-guide/query/gremlin/gremlin.md
+++ b/docs/user-guide/query/gremlin/gremlin.md
@@ -251,3 +251,22 @@ a table of how different parts are mapped is as follows:
 | Entity | Vertex |
 | Edge | Edge |
 | Edge ID | A list with the source and destination of the Edge e.g. `[dest, source]` |
+
+## Custom Features
+
+The GafferPop implementation provides some extra features on top of the
+standard Tinkerpop framework that you can utilise in your queries. These
+are likely specific to how a Gaffer graph operates and may not be available
+in other graph technologies that support Gremlin queries.
+
+### Adding Options to Queries
+
+In standard Gremlin syntax it is possible to add additional key value variables
+into a query via a [`with()` step](https://tinkerpop.apache.org/docs/current/reference/#with-step).
+This feature is utilised to allow some custom properties to be passed in
+for Gaffer specific options:
+
+| Key | Example | Description |
+| --- | --- | --- |
+| `operationOptions` | `g.with("operationOptions", "gaffer.federatedstore.operation.graphIds:graphA").V()` | Allows passing options to the underlying Gaffer Operations, this is the same as the `options` field on a standard JSON query. |
+| `getAllElementsLimit` | `g.with("getAllElementsLimit", 100).V()` | Limits the amount of elements returned if performing an unseeded query e.g. a `GetAllElements` operation. |