Query sharing (Enterprise)

Query sharing is a feature introduced in Lab 2.15, allowing users to create a shareable link for their Cypher query, Graph Style Script, and query parameters with a single click. This enables seamless collaboration among team members.

The Lab utilizes remote storage to securely store the shared data, ensuring sensitive information is protected. Additionally, the system tracks which users viewed the query and when, providing comprehensive access logs for enhanced security and accountability.

💡

Enterprise: Query sharing requires a Memgraph Enterprise license to function. For more information on Memgraph Enterprise and instructions on how to enable it, refer to the enabling Memgraph Enterprise documentation.

💡

Environment: Query sharing is available exclusively when the Lab is started in a Docker environment.

How to set it up

To enable the Query sharing feature in the Lab, you need to set up the remote storage (Memgraph instance) that the Lab will connect to and store query-sharing data.

Query sharing requires a valid Memgraph Enterprise license configured on the Lab side. Ensure that you configure the following environment variables when running Lab with Docker:

VariableDescriptionType
ENTERPRISE_LICENSE_ORG_NAMEEnterprise license organization namestring
ENTERPRISE_LICENSE_KEYEnterprise license keystring

For example:

docker run \
  -p 3000:3000 \
  -e ENTERPRISE_LICENSE_ORG_NAME="My company" \
  -e ENTERPRISE_LICENSE_KEY="key..." \
  memgraph/lab

The enterprise license will be checked once you set up the remote storage. Remote storage should be a new Memgraph instance or a new Memgraph database in a multi-tenant environment.

Using a standalone Memgraph instance as remote storage

In this scenario, Memgraph should be used only for Lab purposes to store query-sharing information. Memgraph can be a community or enterprise version. Make sure your Memgraph is running and then set the following environment variables so Lab can connect to it for remote storage capability.

These two environment variables are required:

VariableDescriptionType
STORAGE_MG_HOSTMemgraph host for the Lab remote storagestring
STORAGE_MG_PORTMemgraph port for the Lab remote storagenumber

These variables are optional and depend on the configuration of the Memgraph instance:

VariableDescriptionType
STORAGE_MG_IS_ENCRYPTEDMemgraph SSL on/off for the Lab remote storageboolean
STORAGE_MG_USERNAMEMemgraph username for the Lab remote storagestring
STORAGE_MG_PASSWORDMemgraph password for the Lab remote storagestring

If your Memgraph instance has SSL defined and there is a username lab and password lab, the complete Docker command should look like this:

docker run \
  -p 3000:3000 \
  -e ENTERPRISE_LICENSE_ORG_NAME="My company" \
  -e ENTERPRISE_LICENSE_KEY="key..." \
  -e STORAGE_MG_HOST=127.0.0.1 \
  -e STORAGE_MG_PORT=7867 \
  -e STORAGE_MG_IS_ENCRYPTED=true \
  -e STORAGE_MG_USERNAME=lab \
  -e STORAGE_MG_PASSWORD=lab \
  memgraph/lab

If there is no username or password and Memgraph is accepting non-SSL connections, omit the optional environment variables:

docker run \
  -p 3000:3000 \
  -e ENTERPRISE_LICENSE_ORG_NAME="My company" \
  -e ENTERPRISE_LICENSE_KEY="key..." \
  -e STORAGE_MG_HOST=127.0.0.1 \
  -e STORAGE_MG_PORT=7867 \
  memgraph/lab

Upon successful configuration, you should see the following log output when starting the Lab:

INFO: [lab] Checking connectivity to remote storage *** with a timeout of *** ms...
INFO: [lab] Enterprise license applied successfully. Enjoy the premium features.
...
INFO: [lab] Remote storage *** successfully connected.

Using a Memgraph multi-tenant environment as remote storage

This scenario works only with Memgraph Enterprise because multi-tenancy is an enterprise feature. In a multi-tenant environment, you can use your existing Memgraph instance with a new database that Lab will use for remote storage to store query-sharing information.

These three environment variables are required:

VariableDescriptionType
STORAGE_MG_HOSTMemgraph host for the Lab remote storagestring
STORAGE_MG_PORTMemgraph port for the Lab remote storagenumber
STORAGE_MG_DATABASE_NAMEMemgraph database name for the Lab remote storagestring

These variables are optional and depend on the configuration of the Memgraph instance:

VariableDescriptionType
STORAGE_MG_IS_ENCRYPTEDMemgraph SSL on/off for the Lab remote storageboolean
STORAGE_MG_USERNAMEMemgraph username for the Lab remote storagestring
STORAGE_MG_PASSWORDMemgraph password for the Lab remote storagestring

Let's say that you already created a new database called lab in your enterprise Memgraph instance for remote storage. For better security, it is recommended to always define usernames and passwords. However, if it accepts non-SSL connections with no username or password, the following command should make Lab successfully connect to the remote storage:

docker run \
  -p 3000:3000 \
  -e ENTERPRISE_LICENSE_ORG_NAME="My company" \
  -e ENTERPRISE_LICENSE_KEY="key..." \
  -e STORAGE_MG_HOST=127.0.0.1 \
  -e STORAGE_MG_PORT=7867 \
  -e STORAGE_MG_DATABASE_NAME=lab \
  memgraph/lab

If your Memgraph instance has SSL defined and there is a username lab and password lab, the complete Docker command should look like this:

docker run \
  -p 3000:3000 \
  -e ENTERPRISE_LICENSE_ORG_NAME="My company" \
  -e ENTERPRISE_LICENSE_KEY="key..." \
  -e STORAGE_MG_HOST=127.0.0.1 \
  -e STORAGE_MG_PORT=7867 \
  -e STORAGE_MG_IS_ENCRYPTED=true \
  -e STORAGE_MG_USERNAME=lab \
  -e STORAGE_MG_PASSWORD=lab \
  memgraph/lab

Upon successful configuration, you should see the following log output when starting the Lab:

INFO: [lab] Checking connectivity to remote storage *** with a timeout of *** ms...
INFO: [lab] Enterprise license applied successfully. Enjoy the premium features.
...
INFO: [lab] Remote storage *** successfully connected.

How it works

Remote storage

For Query sharing to function, the Lab requires a remote storage connection where query-sharing information will be saved. Remote storage should be a new Memgraph instance or a new Memgraph database in a multi-tenant environment.

Remote storage is needed to keep all the information, such as the query, parameters, and other details, in the database, which can contain sensitive or private information. Only a share identifier is shared, ensuring data security. Additionally, having remote storage enables users to connect from different browsers to the same instance of Lab to see the shared query.

This setup also allows administrators to connect to Memgraph, which acts as a remote storage, and access all shares, users, and viewing history. Administrators can also perform migrations. It is essential to set up authentication and role-based permissions in Memgraph used as remote storage for the Lab to ensure data security.

User actions

Users can perform three primary actions with Query sharing:

Create a query share

A user can create a query share from the query execution editor. When a query share is created, the Lab stores information about the creator and all necessary details to run the query, including:

  • Cypher query
  • Graph Style Script
  • Cypher query parameters

The creator can select which results view to display, either Data or Graph view. In the case of multiple queries in a share, the creator can also select which query results to show first. This is particularly useful when sharing a multi-query that involves setup queries followed by a graph algorithm whose results are to be displayed first.

Upon creation, the user receives a URL that can be shared with other team members who have access to the same Lab and Memgraph instance.

View query share history

Users can view a history of their created query shares, including the number of views each share has received.

The history will display all query shares created on the specific Lab instance. If you have created query shares for multiple Memgraph instances, such as production and staging, you will see both in the query history. To view a query share via share link as a viewer, you must be connected to the Memgraph instance where the share was originally created.

Users can delete any query share from the history. Once deleted, the URL associated with that query share will no longer be valid.

💡

Note: Editing a query share is not supported. To modify a query share, you must create a new one.

Access and view a query share

When a recipient clicks on the query share link, they must first connect to Memgraph. All the connection details will be prefilled on the login page, except for authentication data. Once the user is successfully logged in, they can view the shared query and choose to run it or save it to their collection.

Note that you cannot view a query share on a different Memgraph instance from the one where the query share was created.

User definitions and permissions

For Query sharing to function correctly, users should be defined in the Memgraph instance where the shares are created. This is the Memgraph instance that users connect to for running queries, not the remote storage Memgraph that Lab uses. This approach allows tracking of who viewed each query share and enables creators to manage their own shares.

Without user definitions in the Memgraph database, all connections are treated as the same user (Not-Defined user). This means everyone can see all query shares and potentially delete them from the history. Therefore, defining users in the Memgraph instance is essential for maintaining security and proper management of query shares.