Set up connectors

Feature availability

This feature isn't available in all regions. Refer to the data center and regional availability page to check if it's supported in your region and explore alternative solutions.

Before querying data with Lens, you need to set up connections to supported data sources. Lens provides both system connectors for accessing NRDB data and data connectors for connecting to external databases and other data sources.

Requirements

Before you set up data connectors, make sure you meet the following requirements.

Permissions

If you are an Organization Manager, you have capabilities to access all Lens features by default. If you're not an Organization Manager, the Authentication Domain Manager needs to grant you an organization-scoped custom role with the required Lens capabilities, using either of the following methods:

NerdGraph: Create an organization-scoped custom role via NerdGraph, and add the permission IDs from the following tables to the permissionIds array.
UI: Create a new organization-scoped custom role, or edit an existing one, to add the connector or materialized view capabilities from the Query Your Data section, as listed in the following tables.

Important

Some capabilities grant broader access than others. For example, Modify also grants create, update, delete, and query or refresh access. If you only want to grant a narrower capability, select that specific capability instead of Modify.

The following permission IDs control access to Lens connectors:

Capability	Permission ID	Description
Lens Connector > Read	`nr_lens.read.catalogs`	View connectors and their details
Lens Connector > Modify	`nr_lens.read.catalogs` `nr_lens.create.catalogs` `nr_lens.update.catalogs` `nr_lens.delete.catalogs` `nr_lens.query.connector`	View, create, edit, delete, and query connectors
Lens Connector > Other: Query Connectors	`nr_lens.query.connector`	Grants explicit query permission for connectors, without the broader access granted by Modify

The following permission IDs control access to materialized views:

Capability	Permission ID	Description
Lens Materialized Views > Read	`nr_lens.read.materialized_views`	View materialized views
Lens Materialized Views > Modify	`nr_lens.read.materialized_views` `nr_lens.create.materialized_views` `nr_lens.update.materialized_views` `nr_lens.refresh.materialized_views` `nr_lens.delete.materialized_views`	View, create, edit, refresh, and delete materialized views
Lens Materialized Views > Other: Refresh Materialized Views	`nr_lens.refresh.materialized_views`	Grants explicit refresh permission for materialized views, without the broader access granted by Modify

Database access requirements

If your external database restricts access by IP address, you must whitelist New Relic's IP addresses to allow Lens to connect and query your data. Find the list of IP addresses here to add to your database's allowlist.

System connectors

Lens provides three system connectors for accessing NRDB data. These connectors are available automatically and don't require any setup.

Connector	Description	Access level
Telemetry	Access telemetry data from NRDB, such as transactions, logs, and metrics.	Account level. You can only access data from accounts where you have permissions.
Entity	Access entity data from NRDB, including services, hosts, and applications.	Account level. You can only access data from accounts where you have permissions.
Materialized views	Access materialized view data stored in NRDB (results from queries joining multiple databases).	Organization level. All users with Lens access can query materialized views.

Data connectors

Data connectors connect Lens to external data sources like databases, data warehouses, and spreadsheets. To create, edit, or delete connectors, you need specific RBAC permissions.

Access control

Lens provides two ways to control who can query connectors:

RBAC permissions: Users with Lens connectors RBAC permissions can query all connectors in the organization.
Fine-grained access control: Users without broad RBAC permissions can still query specific connectors if granted fine-grained access to those connectors. You set this up when you create the connector, as part of the following procedure.

Create a connector

To set up a data connector:

Go to one.newrelic.com > Administration > Connectors.
Click Create a connector.
Select your connector type from the dropdown menu.
Enter the required connection information for your selected connector type.
To grant this connector access to users or groups who don't have RBAC permissions, configure fine-grained access control from the Access control section:
1. Select the Auth domain containing the users or groups.
2. Select the User or group.
3. Select the Lens Viewer role.
4. To add more users or groups, click Add and repeat the steps above.
Click Create.

After you create a connector:

To view the schema or delete the connector, select the menu from the connector row.
To update access control settings, select the connector, add or remove access grants, and save your changes.
To update the connector configuration, delete and recreate the connector with the new details.

Connector configurations

Select your connector type to view the required fields.

Connect to Google Sheets to query spreadsheet data directly from Lens.

Parameter	Description
Name	A unique name to identify this connector when writing queries. For example, `gsheets` or `employee_data`.
credential_key	The base64-encoded JSON key for your Google Cloud service account. This authenticates Lens with Google Sheets API. See Generate the service account credentials key for instructions.
sheet_id	The ID of your metadata Google Sheet that contains information about all the sheets you want to access through Lens. See Set up Google Sheets access for instructions.

Generate the service account credentials key

To authenticate Lens with Google Sheets, you need to create a Google Cloud service account and generate a JSON key.

Create a service account

To create a Google Cloud service account, follow the instructions in Create service accounts.

Set up permissions for key creation

To create keys for your service account, you need the appropriate permissions. For information on the required permissions, see Required permissions.

Create a JSON key

To generate a JSON key for your service account, follow the steps in Create a service account key.

Convert the JSON key to base64

To use the JSON key in Lens, convert the entire contents of the JSON file to base64 encoding and save it in a text file.

Set up Google Sheets access

After you've generated the credentials key, configure access to your Google Sheets.

To allow Lens to access your data, grant read permissions to the service account email address for each Google Sheet you want to connect.

Create a metadata sheet

To manage the sheets available to Lens, create a new Google Sheet with the following four columns:

Sheetname: The name of each sheet you want to access with Lens. All listed sheets must be accessible by the service account.
Sheetid: The unique identifier for each sheet. You can find this in the sheet URL: https://docs.google.com/spreadsheets/d/SHEET_ID/edit.
Owner: The owner of the sheet. Use Trino as the default value.
Notes: Any additional notes or descriptions for the sheet.

To allow Lens to read the metadata, grant read permission to your service account for the metadata sheet.

Copy the metadata sheet ID

To configure the connector, copy the sheet ID from the metadata sheet URL. The sheet ID appears in the URL as: https://docs.google.com/spreadsheets/d/SHEET_ID/edit.

Important

The Glue Data Catalog and the S3 bucket containing your Iceberg data must be in the same AWS region.

Connect to Apache Iceberg tables stored in AWS using Glue Data Catalog for metadata management.

Grant Lens access to your AWS resources

To connect Lens to your Iceberg tables:

Create an IAM policy

Create an IAM policy with the following permissions to allow Lens to read the Glue metadata and the data files in S3. Replace {REGION}, {ACCOUNT_ID}, {DATABASE_NAME}, and {S3_BUCKET_NAME} with your values. Note the policy name you enter, as you'll need it to attach this policy to the IAM role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "glue:GetDatabase",
        "glue:GetTable",
        "glue:GetTables",
        "glue:SearchTables",
        "glue:GetPartition",
        "glue:GetPartitions",
        "glue:BatchGetPartition"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:glue:{REGION}:{ACCOUNT_ID}:catalog",
        "arn:aws:glue:{REGION}:{ACCOUNT_ID}:database/{DATABASE_NAME}",
        "arn:aws:glue:{REGION}:{ACCOUNT_ID}:table/*"
      ]
    },
    {
      "Action": ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::{S3_BUCKET_NAME}",
        "arn:aws:s3:::{S3_BUCKET_NAME}/*"
      ]
    }
  ]
}

Create an IAM role with a trust relationship

Create an IAM role and configure the trust relationship to allow the Lens service account to assume it. When setting up the role, use these values:

Trusted entity type: AWS account
Account ID: 017663287629 (New Relic's AWS account)
Require external ID: Enabled. AWS requires a value to complete role creation, so enter a temporary placeholder (for example, temp-id). You'll replace this with the external ID Lens generates in the next step.
Permissions policy: Search for the policy name you created in the previous step and select it.
The trust policy should match the following format. Replace <AUTO_GENERATED_EXTERNAL_ID_FROM_LENS_UI> with the same temporary placeholder you entered above — you'll update this value again with the real, Lens-generated external ID in a later step.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::017663287629:user/service_fdp_customer_account_data_access"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<AUTO_GENERATED_EXTERNAL_ID_FROM_LENS_UI>"
        }
      }
    }
  ]
}
```
After creating the role, open the role's summary page and copy the Role ARN. You'll need this ARN to create the connector in the next step.

Create the connector

Go to one.newrelic.com > Administration > Connectors, click Create a connector, select Iceberg, and enter the following details:

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries. The name must start with `nrlens-`.	`nrlens-CostDB`, `nrlens-Customermetadata`
aws_region	The AWS region where your Iceberg tables are stored. Get this from your infrastructure team.	`us-east-2`
glue_catalog_id	Your 12-digit AWS Account ID that uniquely identifies your Glue Data Catalog within the region. Find this in the AWS Console under Account Settings.	`123456789012`
aws_iam_role_arn	The Role ARN you copied in the previous step.	`arn:aws:iam::123456789012:role/ExampleRole`

Click Create. Lens auto-generates an external ID for the connector.

Update the trust policy with the generated external ID

Open the connector's detail view and copy the auto-generated external ID.
In AWS, edit the IAM role's trust policy and replace the temporary placeholder value in sts:ExternalId with the external ID you copied from Lens.

Connect to Snowflake data warehouses to query your cloud data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`Employeedata`
username	Your Snowflake username for authentication.	`user123`
password	The password for your Snowflake user.	`password@123`
connection-url	The JDBC URL to connect to Snowflake. Format: `jdbc:snowflake://ACCOUNT.snowflakecomputing.com`.	`jdbc:snowflake://ACCOUNT.snowflakecomputing.com`
account	Your Snowflake account identifier. Find this in your Snowflake URL or in the Snowflake Console under Admin > Accounts.	`ACCOUNT`
database	The name of the Snowflake database you want to connect to.	`DATABASE`
role	The Snowflake role assigned to your user. This determines your access permissions.	`ROLE`
warehouse	The name of the Snowflake warehouse to use for compute resources.	`WAREHOUSE`

Connect to PostgreSQL databases to query your relational data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`salesdata`
connection-url	The JDBC URL to connect to PostgreSQL. Format: `jdbc:postgresql://[host]:[port]/[database]`.	`jdbc:postgresql://cluster.amazonaws.com:5432/test_db`
username	Your PostgreSQL database username.	`username`
password	The password for your PostgreSQL user.	`password`

Connect to MySQL databases to query your relational data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`CRMdata`
connection-url	The JDBC URL to connect to MySQL. Format: `jdbc:mysql://[host]:[port]/[database]`.	`jdbc:mysql://test-db-mysql.cluster-cl3aokvievxs.us-east-2.rds.amazonaws.com:3306/test_db`
username	Your MySQL database username.	`username`
password	The password for your MySQL user.	`password`

Connect to Amazon Redshift data warehouses to query your analytics data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`AppDB`
connection-url	The JDBC URL to connect to Redshift. Format: `jdbc:redshift://[host]:[port]/[database]`.	`jdbc:redshift://example.net:5439/database`
username	Your Redshift database username.	`root`
password	The password for your Redshift user.	`password`

Connect to Google BigQuery to query your cloud data warehouse tables.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`bigquery_data`
project_id	Your Google Cloud project ID.	`my-gcp-project`
credential_key	The base64-encoded JSON key for your Google Cloud service account. This authenticates Lens with BigQuery. Refer to Generate the service account credentials key for instructions.	`<base64-encoded-json-key>`

Generate the service account credentials key

To authenticate Lens with BigQuery, you need a Google Cloud service account with the correct BigQuery roles, and a JSON key for that account.

Create a service account

If you don't already have a service account, refer to Create service accounts to create one.

Grant BigQuery roles

Refer to Grant an IAM role to grant the service account both of these roles, as reading data and running queries are separate BigQuery permissions:

BigQuery Data Viewer (roles/bigquery.dataViewer): Lets the connector read table data and metadata. You can scope this to specific datasets instead of the whole project for tighter access.
BigQuery Job User (roles/bigquery.jobUser): Lets the connector run queries. Grant this at the project level, as job execution isn't a dataset-level permission in BigQuery.

Create a JSON key

To generate a JSON key for your service account, refer to Create a service account key for instructions.

Convert the JSON key to base64

To use the JSON key in Lens, convert the entire contents of the JSON file to base64 encoding:

bash

$base64 -i your-key-file.json | tr -d '\n'

When you create the connector, copy the output into the credential_key field.

Connect to Prometheus to query your metrics data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`MetricsDB`
uri	The URL of your Prometheus server.	`http://localhost:9090`
username (optional)	Username for basic authentication if your Prometheus server requires it.	`username`
password (optional)	Password for basic authentication.	`password`
query_chunk_duration (optional)	The duration of each query chunk sent to Prometheus. Smaller chunks reduce memory usage but increase the number of requests.	`1d`
max_query_range (optional)	The maximum time range for queries. Lens divides this range into chunks based on `query_chunk_duration`.	`21d`
cache_ttl (optional)	How long to cache values from this data source before refreshing.	`30s`

Connect to MongoDB databases to query your document data.

Important

You can't read your connection URL after it's set because it contains sensitive information, such as your password.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`CustomerDB`
connection-url	The MongoDB connection string. Format: `mongodb://<user>:<pass>@<host>:<port>/`. Both username and password must be URL encoded.	`mongodb://user:pass@cluster.mongodb.net:27017/`

For MongoDB Atlas users: The username and password you enter in Lens are your Database User credentials, not the credentials you use to log into the Atlas web UI.

URL encoding: Your username and password must be URL encoded.

Connect to Elasticsearch to query your search and analytics data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.
host	The hostname or IP address of your Elasticsearch server.
port	The port number for your Elasticsearch server.
security	The security method for authentication.
username	Your Elasticsearch username for authentication.
password	The password for your Elasticsearch user.
tls_enabled (optional)	Enable TLS for secure connections to your Elasticsearch server.

Connect to AWS CloudWatch to query your cloud monitoring data.

Important

The CloudWatch connector is region-specific. Create separate connectors for each AWS region you want to query.

Grant Lens access to CloudWatch

To connect Lens to your CloudWatch metrics:

Create an IAM policy

Create an IAM policy with the following permissions to allow Lens to read CloudWatch metrics from your AWS account. Note the policy name you enter, as you'll need it to attach this policy to the IAM role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:ListMetrics",
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "tag:GetResources"
      ],
      "Resource": "*"
    }
  ]
}

Create an IAM role with a trust relationship

Create an IAM role and configure the trust relationship to allow the Lens service account to assume it. When setting up the role, use these values:

Trusted entity type: AWS account
Account ID: 017663287629 (New Relic's AWS account)
Require external ID: Enabled. AWS requires a value to complete role creation, so enter a temporary placeholder (for example, temp-id). You'll replace this with the external ID Lens generates in the next step.
Permissions policy: Search for the policy name you created in the previous step and select it.
The trust policy should match the following format. Replace <AUTO_GENERATED_EXTERNAL_ID_FROM_LENS_UI> with the same temporary placeholder you entered above — you'll update this value again with the real, Lens-generated external ID in a later step.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::017663287629:user/service_fdp_customer_account_data_access"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<AUTO_GENERATED_EXTERNAL_ID_FROM_LENS_UI>"
        }
      }
    }
  ]
}
```
After creating the role, open the role's summary page and copy the Role ARN. You'll need this ARN to create the connector in the next step.

Create the connector

Go to one.newrelic.com > Administration > Connectors, click Create a connector, select AWS CloudWatch, and enter the following details, using the Role ARN from the previous step:

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries. The name must start with `nrlens-`.	`nrlens-cloudwatch-metrics`
aws_region	The AWS region where your CloudWatch data is stored.	`us-east-2`
aws_iam_role_arn	The Role ARN you copied in the previous step.	`arn:aws:iam::123456789012:role/LensCloudwatchAccessRole`

Click Create. Lens auto-generates an external ID for the connector.

Update the trust policy with the generated external ID

Open the connector's detail view and copy the auto-generated external ID.
In AWS, edit the IAM role's trust policy and replace the temporary placeholder value in sts:ExternalId with the external ID you copied from Lens.

Connect to ClickHouse to query your analytics data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`AnalyticsDB`
username	Your ClickHouse database username.	`admin`
password	The password for your ClickHouse user.	`password`
connection-url	The JDBC URL to connect to ClickHouse. Format: `jdbc:clickhouse://<host>:8123/<database>?ssl=true`.	`jdbc:clickhouse://clickhouse.example.com:8123/analytics_db?ssl=true`

Connect to Microsoft SQL Server to query your relational data.

Parameter	Description	Sample value
Name	A unique name to identify this connector when writing queries.	`SalesDB`
connection-url	The JDBC URL to connect to SQL Server. Format: `jdbc:sqlserver://<host>:<port>;databaseName=<database>;encrypt=false`.	`jdbc:sqlserver://sqlserver.example.com:1433;databaseName=sales_db;encrypt=false`
username	Your SQL Server database username.	`sa`
password	The password for your SQL Server user.	`password`

Connect to Databricks (Azure) to query your data directly from Lens.

Parameter	Description
Name	A unique name to identify this connector when writing queries. For example, `databricks` or `employee_data`.
rest_catalog_uri	The uri for the databricks catalog you are querying. Format: `https://adb-<workspace-id>.azuredatabricks.net/api/2.1/unity-catalog/iceberg-rest`
rest_catalog_warehouse	The catalog name for your Databricks (Azure) workspace.
oauth2_server_uri	The OAuth2 server URI for your Databricks (Azure) workspace that you want to query through Lens.
oauth2_token	Create an OAuth2 token for your Databricks (Azure) workspace.
azure_access_key	The access key for your Azure Storage account

Verify your setup

To confirm a connector is working:

View its schema from the menu on the connector row to confirm Lens can see your data source's tables.
Query the connector using the connection_name.schema.table format. If your query returns results, the connector is set up correctly.

If you're setting up a connector to support a materialized view, successfully creating the materialized view confirms the connector works end to end.

Lens overview

Learn about Lens features, capabilities, and use cases.

Query data with Lens

Query data in Query Builder, Notebooks, and dashboards.

Materialized views

Create and manage materialized views for better performance.

Feature availability

Requirements .css-21sua1{background:none;border:none;width:0;padding:0;}

Permissions

Important

Materialized view permissions

Database access requirements

System connectors

Data connectors

Access control

Create a connector

Connector configurations

Google Sheets connector

Iceberg connector

Snowflake connector

PostgreSQL connector

MySQL connector

Redshift connector

BigQuery connector

Prometheus connector

MongoDB connector

Elasticsearch connector

AWS CloudWatch connector

ClickHouse connector

SQL Server connector

Databricks (Azure) connector

Verify your setup

Related topics

Lens overview

Query data with Lens

Materialized views

Requirements