Use Azure Digital Twins Explorer (preview)
Azure Digital Twins Explorer is a tool for visualizing and working with Azure Digital Twins. This article describes the features of Azure Digital Twins Explorer, and how to use them to manage the data in your Azure Digital Twins instance.
This tool is currently in public preview.
How to access
The main way to access Azure Digital Twins Explorer is through the Azure portal.
To open Azure Digital Twins Explorer for an Azure Digital Twins instance, first navigate to the instance in the portal, by searching for its name in the portal search bar. Next, select the Open Azure Digital Twins Explorer (preview) button to open an Azure Digital Twins Explorer window connected to the instance.
Switch contexts within the app
Once in the application, you're also able to change which instance is currently connected to the explorer, by selecting the instance name from the top toolbar.
This will bring up the Azure Digital Twins URL modal, where you can enter the host name of another Azure Digital Twins instance after the https:// to connect to that instance.
At this time, the ability to switch contexts within the app is not available for personal Microsoft Accounts (MSA). MSA users will need to access the explorer from the correct instance in the Azure portal, or may connect to a certain instance through a direct link to the environment.
Query your digital twin graph
You can use the Query Explorer panel to perform queries on your graph.
Enter the query you want to run and select the Run Query button. This will load the query results in the Twin Graph panel.
Query results containing relationships can only be rendered in the Twin Graph panel if the results include at least one twin as well. While queries that return only relationships are possible in Azure Digital Twins, you can only view them in Azure Digital Twins Explorer by using the Output panel.
Overlay query results
You can check the Overlay results box before running your query if you'd like the results to be highlighted from what is currently being shown in the Twin Graph panel, instead of completely replacing the panel's contents with the new query results.
If the query result includes something that is not currently being shown in the Twin Graph panel, the element will be added onto the existing view.
Save and rerun queries
Queries can be saved in local storage in your browser, making them easy to select and rerun.
Local browser storage means that saved queries will not be available in other browsers apart from the one where you saved them, and they will remain in the browser storage indefinitely until the local storage is cleared.
To save a query, enter it into the query box and select the Save icon at the right of the panel. Enter a name for the saved query when prompted.
Once the query has been saved, it is available to select from the Saved Queries dropdown menu to easily run it again.
To delete a saved query, select the X icon next to the name of the query when the Saved Queries dropdown menu is open.
For large graphs, it's suggested to query only a limited subset and then load the remainder of the graph as required. You can double-click on a twin in the Twin Graph panel to retrieve additional related nodes.
Explore the Twin Graph
The Twin Graph panel allows you to explore the twins and relationships in your instance.
You can use this panel to view your twins and relationships.
The Twin Graph panel also provides several abilities to customize your graph viewing experience:
- Edit twin graph layout
- Control twin graph expansion
- Show and hide twin graph elements
- Filter and highlight twin graph elements
View twins and relationships
Run a query using the Query Explorer to see the twins and relationships in the query result displayed in the Twin Graph panel.
The query to display all twins and relationships is
SELECT * FROM digitaltwins.
View twin and relationship properties
To view the property values of a twin or a relationship, select the twin or relationship in the Twin Graph and use the Toggle property inspector button to expand the Properties panel. This panel will display all the properties associated with the element, along with their values. It also includes default values for properties that have not yet been set.
Properties generally appear in white text, but may also appear in the following colors to indicate additional information:
Red text for model: Indicates that the model for the twin can't be found. This can happen if the model has been deleted since the twin was created.
Yellow text for property: Indicates that the property is not part of the model definition that the twin is using. This can happen if the model for the twin has been replaced or changed since the property was created, and the property no longer exists in the most recent version of the model. Twins with outdated properties cannot be updated, unless the update also corrects or removes the outdated properties.
View a twin's relationships
You can also quickly view the code of all relationships that involve a certain twin (including incoming and outgoing relationships).
To do this, right-click a twin in the graph, and choose Get relationships. This brings up a Relationship Information modal displaying the JSON representation of all incoming and outgoing relationships.
Edit twin graph layout
You can rearrange the twins into different configurations by clicking and dragging them around the Twin Graph screen.
You can also apply one of several layout algorithms to the graph from the options in the Run Layout menu.
Control twin graph expansion
While viewing a query result in the Twin Graph panel, you can double-click a twin to have the graph fetch its relationships and related twins and display them if they're not already present in the view. You can customize this expansion by setting a size and direction to determine how many twins to fetch.
To set the number of layers to expand, use the Expansion Level option. This number indicates how many layers of relationships to fetch from the selected twin.
To indicate which types of relationships to follow when expanding, use the Expansion Mode button. This allows you to select from just incoming, just outgoing, or both incoming and outgoing relationships.
Show and hide twin graph elements
You can toggle the option to hide twins or relationships from the graph view.
To hide a twin or relationship, right-click it in the Twin Graph window. This will bring up a menu with an option to hide the element or other related elements.
You can also hide multiple twins or relationships at once by using the CTRL/CMD or SHIFT keys to multi-select several elements of the same type in the graph. From here, follow the same right-click process to see the hide options.
To return to showing all twins after some have been hidden, use the Show All button. To return to showing all relationships, use the Show All Relationships button.
Filter and highlight twin graph elements
You can filter the twins and relationships that appear in the graph by text, by selecting this Filter icon:
You can also highlight the twins and graph that appear in the graph by text, by selecting this Highlight icon:
Manage twins and graph
This section describes how to perform the following management activities:
- Create twins, with or without initial properties
- Create relationships between twins
- Edit twins and relationships
- Delete twins and relationships
For information about the viewing experience for twins and relationships, see Explore twins and the Twin Graph.
You can create a new digital twin from its model definition in the Models panel.
To create a twin from a model, find that model in the list and choose the Create a Twin icon next to the model name. You'll be asked to enter a name for the new twin, which must be unique. Then save the twin, which will add it to your graph.
To add property values to your twin, see Edit twins and relationships.
To create a relationship between two twins, start by selecting the source twin for the relationship in the Twin Graph window. Next, hold down a CTRL/CMD or SHIFT key while you select a second twin to be the target of the relationship.
Once the two twins are simultaneously selected, right-click either one of the twins. This will bring up a menu with an option to Add relationships between them.
This will bring up the Create Relationship dialog, which shows the source twin and target twin of the relationship, followed by a Relationship dropdown menu that contains the types of relationship that the source twin can have (defined in its DTDL model). Select an option for the relationship type, and Save the new relationship.
Edit twins and relationships
To view the property values of a twin or a relationship, select the element in the Twin Graph and use the Toggle property inspector button to expand the Properties panel.
You can use this panel to directly edit writable properties. Update their values inline, and click the Patch twin (save) button at the top of the panel to save your changes. When the update is saved, the screen displays a modal window showing the JSON Patch operation that was applied by the update API.
Delete twins and relationships
To delete a twin or a relationship, right-click it in the Twin Graph window. This will bring up a menu with an option to delete the element.
You can delete multiple twins or multiple relationships at once, by using the CTRL/CMD or SHIFT keys to multi-select several elements of the same type in the graph. From here, follow the same right-click process to delete the elements.
You can also choose to delete all of the twins in your instance at the same time, using the Delete All Twins button in the top toolbar.
Explore models and the Model Graph
Models can be viewed both in the Models panel on the left side of the Azure Digital Twins Explorer screen, and in the Model Graph panel in the middle of the screen.
You can use these panels to view your models.
The Model Graph panel also provides several abilities to customize your graph viewing experience:
- Edit model graph layout
- Filter and highlight model graph elements
- Upload model images to represent models in the graphs
You can view a flat list of the models in your instance in the Models panel. This list is searchable using the Search bar in the panel.
You can use the Model Graph panel to view a graphical representation of the models in your instance, along with the relationships, inheritance, and components that connect them to each other.
View model definition
To see the full definition of a model, find that model in the Models pane and choose the View Model icon next to the model name. This will display a Model Information modal showing the raw DTDL definition of the model.
You can also view a model's full definition by selecting it in the Model Graph, and using the Toggle model details button to expand the MODEL DETAIL panel. This panel will also display the full DTDL code for the model.
Edit model graph layout
You can rearrange the models into different configurations by clicking and dragging them around the Model Graph screen.
You can also apply one of several layout algorithms to the model graph from the options in the Run Layout menu.
Filter and highlight model graph elements
You can filter the types of connections that appear in the Model Graph. Turning off one of the connection types via the switches in this menu will prevent that connection type from displaying in the graph.
You can also filter the models and connections that appear in the graph by text, by selecting this Filter icon:
You can highlight the models and connections that appear in the graph by text, by selecting this Highlight icon:
Upload model images
You can upload custom images to represent different models in the Model Graph and Twin Graph views. You can upload images for individual models, or for several models at once.
These images are stored in local browser storage. This means that the images will not be available in other browsers apart from the one where you saved them, and they will remain in the browser storage indefinitely until the local storage is cleared.
To upload an image for a single model, find that model in the Models panel and choose the Upload Model Image icon next to the model name. In the file selector box that appears, navigate on your machine to the image file you want to upload for that model. Choose Open to upload it.
You can also upload model images in bulk.
First, use the following instructions to set the image file names before uploading. This enables Azure Digital Twins Explorer to automatically assign the images to the correct models after upload.
- Start with the model ID value (for example,
- Replace instances of ":" with "_" (the example becomes
- Replace instances of ";" with "-" (the example becomes
- Make sure the file has an image extension (the example becomes something like
If you try to upload an image that does not map to any existing model using the criteria above, the image will not be uploaded or stored.
Then, to upload the images at the same time, use the Upload Model Images icon at the top of the Models panel. In the file selector box, choose which image files to upload.
You can use the Models panel on the left side of the Azure Digital Twins Explorer screen to perform management activities on the entire set of models, or on individual models.
With this panel, you can complete the following model management activities:
- Upload models into your Azure Digital Twins instance
- Delete models from your instance
- Refresh models to reload the list of all models into this panel
For information about the viewing experience for models, see Explore models and the Model Graph.
You can upload models from your machine by selecting them individually, or by uploading an entire folder of models at once.
To upload one or more models that are individually selected, select the Upload a model icon showing an arrow pointing up into a cloud.
In the file selector box that appears, navigate on your machine to the model(s) you want to upload. You can select one or more JSON model files and select Open to upload them.
To upload a folder of models, including everything that's inside it, select the Upload a directory of Models icon showing a file folder.
In the file selector box that appears, navigate on your machine to a folder containing JSON model files. Select Open to upload that top-level folder and all of its contents.
If a model references another model in its definition, like when you're defining relationships or components, the model being referenced needs to be present in the instance in order to upload the model that uses it. If you're uploading models one-by-one, that means that you should upload the model being referenced before uploading any models that use it. If you're uploading models in bulk, you can select them both in the same import and Azure Digital Twins will infer the order to upload them in.
You can use the Models panel to delete individual models, or all of the models in your instance at once.
To delete a single model, find that model in the list and choose the Delete Model icon next to the model name.
To delete all of the models in your instance at once, choose the Delete All Models icon at the top of the Models panel.
When you open Azure Digital Twins Explorer, the Models panel should automatically show all available models in your environment.
However, you can manually refresh the panel at any time to reload the list of all models in your Azure Digital Twins instance. To do this, select the Refresh models icon of an arrow pointing down out of a cloud.
You can use the import feature to add twins, relationships, and models to your instance. This can be useful for creating many twins, relationships, and/or models at once.
Create import file
The first step in importing a graph is creating a file representing the twins and relationships you want to add.
The import file can be in either of these two formats:
- The custom Excel-based format described in the remainder of this section. This allows you to upload twins and relationships.
- The JSON-based format generated on graph export. This can contain twins, relationships, and/or models.
To create a custom graph in Excel, use the following format.
Each row represents an element to create: either a twin, a relationship, or a combination of twin and corresponding relationship. Use the following columns to structure the twin or relationship data. The column names can be customized, but they should remain in this order.
|ModelID||ID||Relationship (source)||Relationship Name||Init Data|
The DTMI model ID for a twin that should be created.
You can leave this column blank for a row if you want that row to create only a relationship (no twins).
The unique ID for a twin.
If a new twin is being created in this row, this will be the ID of the new twin.
If there is relationship information in the row, this ID will be used as the target of the relationship.
The ID of a twin that should be the source twin for a new relationship.
You can leave this column blank for a row if you want that row to create only a twin (no relationships).
The name for the new relationship to create. The relationship direction will be from the twin in column C to the twin in column B.
A JSON string containing property settings for the twin to be created. The properties must match those defined in the model from column A.
Here is an example .xlsx file creating a small graph of two floors and two rooms.
You can view this file and additional .xlsx graph examples in the Azure Digital Twins Explorer repository on GitHub.
The properties and relationships described in the .xlsx must match what's defined in the model definitions for the related twins.
Import file to Azure Digital Twins Explorer
Once you have a file on your machine that's ready to be imported, select the Import Graph icon in the Twin Graph panel.
In the file selector box that appears, navigate on your machine to the graph file (.xlsx or .json) that you want to upload and choose Open to upload it.
Azure Digital Twins will open an Import panel showing a preview of the graph to be imported. To confirm, select the Save icon in the upper-right corner of the panel.
If import is successful, a modal window will display the number of models, twins, and relationships that were uploaded.
Export graph and models
You can use the export feature to export partial or complete graphs, including models, twins, and relationships. Export serializes the twins and relationships from the most recent query results, as well as all models in the instance, to a JSON-based format that you can download to your machine.
To begin, use the Query Explorer panel to run a query that selects the twins and relationships that you want to download. This will populate them in the Twin Graph panel.
The query to display all twins and relationships is
SELECT * FROM digitaltwins.
Once the Twin Graph panel is showing the portion of the graph you want to download, select the Export Graph icon.
This action enables a Download link in the Twin Graph box. Select it to download a JSON-based representation of the query result, and all the models in your instance, to your machine.
This file can be edited and/or re-uploaded to Azure Digital Twins through the import feature.
Link to your environment
You can share your Azure Digital Twins Explorer environment with others to collaborate on work. This section describes how to send your Azure Digital Twins Explorer environment to someone else and verify they have the permissions to access it.
To share your environment, you can send a link to the recipient that will open an Azure Digital Twins Explorer window connected to your instance. Use the link below and replace the placeholders for your tenant ID and the host name of your Azure Digital Twins instance.
The value for the host name placeholder is not preceded by https:// here.
Here is an example of a URL with the placeholder values filled in:
For the recipient to view the instance in the resulting Azure Digital Twins Explorer window, they must log into their Azure account, and have Azure Digital Twins Data Reader access to the instance (you can read more about Azure Digital Twins roles in Security). For the recipient to make changes to the graph and the data, they must have the Azure Digital Twins Data Owner role on the instance.
Link with a query
You may want to share an environment and specify a query to execute upon landing, to highlight a subgraph or custom view for a teammate. To do this, start with the URL for the environment and add the query text to the URL as a querystring parameter:
The query text should be URL encoded.
You can copy the query text from the Query Explorer window and paste it into the URL window in the correct spot at the end of the URL. Submitting this URL should convert the query text to use the proper URL encoding.
You can also use an independent URL encoder to convert the query text.
Here's an example of the parameter for a query to SELECT * FROM digitaltwins:
You can then share the completed URL.
You can enable several advanced setting options for Azure Digital Twins Explorer.
Clicking the settings cog in the top right corner allows the configuration of the following advanced features:
Eager Loading: Accessible via the Settings cog in the top toolbar. When a query returns twins that have relationships to other twins that are not included in the query results, this feature will load the "missing" twins before rendering the graph.
Caching: Accessible via the Settings cog in the top toolbar. When this feature is enabled, Azure Digital Twins Explorer will keep a local cache of relationships and models in memory to improve query performance. These caches are cleared on any write operations on the relevant elements, as well as on browser refresh.
Console: Accessible via the Settings cog in the top toolbar. This feature enables display of a console window, capable of using simple shell functions for working with the graph.
Output: Accessible via the Settings cog in the top toolbar. This feature enables display of an output window, which shows a diagnostic trace of operations.
Customize panel layout: You can edit the position of the panels that make up Azure Digital Twins Explorer (Query Explorer, Models, Twin Graph, Model Graph). To move a panel to a different location, click and hold the panel name, and drag it to its new desired position.
The panel positions will be reset upon refresh of the browser window.
Learn about writing queries for the Azure Digital Twins twin graph: