Visualize data

Authenticate with the CLI

Authenticate using a personal access token:

viam login

For alternative authentication methods, see Authenticate.

Find your organization ID

The following steps require your organization ID. To find, it use the following command:

viam organizations list

Configure a new database user

Configure a new database user. The database user will be able to connect to your data, which is stored in a MongoDB Atlas Data Federation instance.

Provide your organization’s org-id from step 2, and a password for your database user. Your password must be at least 8 characters long with 1 uppercase, and 1 numeric character.

viam data database configure --org-id=<YOUR-ORGANIZATION-ID> --password=<NEW-DBUSER-PASSWORD>

Determine the connection URI

Determine the connection URI (also known as a connection string) for your organization’s MongoDB Atlas Data Federation instance by running the following command with the organization’s org-id from step 2:

viam data database hostname --org-id=abcd1e2f-a1b2-3c45-de6f-ab123456c123

MongoDB Atlas Data Federation instance hostname: data-federation-abcd1e2f-a1b2-3c45-de6f-ab123456c123-0z9yx.a.query.mongodb.net
MongoDB Atlas Data Federation instance connection URI: mongodb://db-user-abcd1e2f-a1b2-3c45-de6f-ab123456c123:YOUR-PASSWORD-HERE@data-federation-abcd1e2f-a1b2-3c45-de6f-ab123456c123-0z9yx.a.query.mongodb.net/?ssl=true&authSource=admin

This command returns the:

• hostname: the MongoDB Atlas Data Federation instance hostname

• connection URI: the MongoDB Atlas Data Federation instance connection uniform resource indicator. This is the connection URI to your organization’s MongoDB Atlas Data Federation instance, which is of the form:

  mongodb://<USERNAME>:<YOUR-PASSWORD>@<HOSTNAME>/?ssl=true&authSource=admin
  

Most MQL-compatible database clients require the connection URI, along with your user credentials, to connect to this server.

Some MQL-compatible database client instead require a hostname and database name, along with your user credentials, to connect to this server. For sensor data, this database name will be sensorData.

Choose Grafana instance

Install or set up Grafana. You can use either a local instance of Grafana Enterprise or Grafana Cloud. The free trial version of Grafana Cloud is sufficient for testing.

Install connector to MongoDB data source

Navigate to your Grafana web UI. Go to Connections > Add new connection and add the Grafana MongoDB data source plugin to your Grafana instance.

Configure a data connection

On the page of the Grafana MongoDB data source that you just installed, select Add new data source.

Enter the following information in the configuration UI for the plugin:

• Connection string: Enter the following connection string. Then replace <MONGODB-ATLAS-DF-HOSTNAME> with your database hostname as configured with the viam data database configure command. The <DATABASE-NAME> for sensor data is sensorData.

  mongodb://<MONGODB-ATLAS-DF-HOSTNAME>/<DATABASE-NAME>?directConnection=true&authSource=admin&tls=true
  

• User: Enter the following username, substituting your organization ID for <YOUR-ORG-ID>:

  db-user-<YOUR-ORG-ID>
  

• Password: Enter the password for the database user. This is the password provided when configuring data query.

  

For more information on the Grafana MongoDB plugin, see Configure the MongoDB data source.

Use Grafana for dashboards

With your data connection established, Grafana can now access all synced sensor data under your organization, from any machine.

You can now build dashboards that provide insight into your data.

You can also query and transform your data. This way, you can visualize different things, such as:

• a single day’s data
• a single machine’s or component’s data
• outliers in your data

Query data from Grafana

You can also use query language directly in Grafana using the MongoDB Query Editor, which enables data query functionality similar to that of the MongoDB shell, mongosh.

For example, try the following query to obtain readings from a sensor, replacing sensor-1 with the name of your component:

sensorData.readings.aggregate([
  {
    $match: {
      component_name: "sensor-1",
      time_received: { $gte: ISODate(${__from}) }
    }
  },
  { $limit: 1000 }
])

This query uses the Grafana global variable $__from, which is populated by the value set from the From dropdown menu on your dashboard. The value is dynamically updated when you change your desired time range from that dropdown menu. See Grafana’s Global variables documentation for more information.

Optimize your queries

For optimal performance when querying large datasets, see query optimization and performance best practices.

Install connector to MongoDB data source

Some visualization clients are able to connect to the Viam MongoDB Atlas Data Federation instance natively, while others require that you install and configure an additional plugin or connector. For example, Tableau requires both the Atlas SQL JDBC Driver as well as the Tableau Connector in order to successfully connect and access data.

Check with the documentation for your third-party visualization tool to be sure you have the required additional software installed to connect to a MongoDB Atlas Data Federation instance.

Configure a data connection

Most third-party visualization tools require the connection URI (also called the connection string) to that database server, and the credentials to authenticate to that server in order to visualize your data. Some third-party tools instead require a hostname and database name of the database server. This is what they look like:

mongodb://db-user-abcdef12-abcd-abcd-abcd-abcdef123456:YOUR-PASSWORD-HERE@data-federation-abcdef12-abcd-abcd-abcd-abcdef123456-e4irv.a.query.mongodb.net/?ssl=true&authSource=admin

mongodb://db-user-abcdef12-abcd-abcd-abcd-abcdef123456:YOUR-PASSWORD-HERE@data-federation-abcdef12-abcd-abcd-abcd-abcdef123456-e4irv.a.query.mongodb.net/sensorData?ssl=true&authSource=admin

mongodb://<MONGODB-ATLAS-DF-HOSTNAME>/<DATABASE-NAME>?directConnection=true&authSource=admin&tls=true

mongodb://data-federation-abcdef12-abcd-abcd-abcd-abcdef123456-e4irv.a.query.mongodb.net/sensorData?directConnection=true&authSource=admin&tls=true

db-user-<YOUR-ORG-ID>

Use visualization tools for dashboards

Some third-party visualization tools support the ability to directly query your data within their platform to generate more granular visualizations of specific data. If available, you can use this functionality to visualize different things, such as:

• a single day’s data
• a single machine’s or component’s data
• outliers in your data

While every third-party tool is different, you would generally query your data using either SQL or MQL. See the guide on querying data for more information. For optimal performance when querying large datasets, see the query optimization and performance best practices section.