GraphXR’s Mapping Editor lets you map data in a single CSV file or SQL table to a graph pattern or model. You can map just the data you want; you need not import the entire table. The mapping queries the data of interest and converts it to graph data, assigning it to categories, properties, relationships, and key values you specify.

You can:

  • Map a table column as a static Category or Relationship label, map additional columns as properties, and create nodes and edges according to properties set as key values.

  • Map the values within a table column as dynamic Category or Relationship labels. This maps unique values within the column to separate Categories (or Relationships) and creates nodes and edges accordingly. This can help you visualize changes in data that’s updated periodically.
    To create a dynamic mapping, you enter a CSV column name in curly braces { } in the Mapping Editor’s Category Name or Relationship Name field. To make the labels more readable, additional text can be included both before and after the name (e.g. Text{Column Name}MoreText).

For example, the mapping shown above helps to visualize and work with photo assets by location and date, since separate categories are created for unique values found in a PlaceName column, and separate relationships are defined for unique values found in a Date Created column.

Once you create a mapping, you can:

  • Save, apply, and edit the mapping.

  • Export a saved mapping as a .JSON file. You can include this with the original data, and import to other GraphXR projects.

Creating a CSV Mapping

To illustrate, we start with an example CSV file that contains a table (with headers) of photographic images and associated metadata such as photographer, image ID, size, date taken, keywords and ratings, and location (place names and latitude-longitude).

Using static and dynamic mapping, we can design a mapping to connect location, ratings and authors of photographic images. We’ll create Photos, Rating, and Author categories and map appropriate properties from the CSV as follows:

  • Photos can include the pkey (since we have one), photo ID number, name, url, image size, date taken, provider, copyright, place name, latitude and longitude, state, and country.

  • Rating can include Rating.

  • Author can include Provider.

We’ll also map dynamic relationships as:

  • RATED_AT_{Rating} to connect Image and Rating nodes with edges labeled by Rating.

  • TAKEN_BY_{Provider} to connect Image and Author nodes with edges labeled by Provider.

Mapping data from a table in an SQL relational database uses the same mapping interface. The SQL query tab does include a Load Without Mapping button to import the entire table you’ve specified. This isn’t needed for a CSV. To load an entire CSV file without mapping, simply drag and drop it on the graph space.

To create a mapping:

  1. The Mapping Editor is only available once you have loaded a CSV file. In the Query panel, open the CSV tab, click Load CSV, navigate to your CSV file, and click Open.

    The file name and number of rows and columns are displayed next to the Load CSV button. The contents of the file including its column headings are displayed in a data table, 10 records at a time. Below that are the controls to create, update and apply a mapping and to access saved mappings.
    NOTE: A mapping will apply to the CSV file that’s loaded. A mapping can also be applied to a different CSV file if the column headers and properties specified in the mapping are present.

  2. Scroll to the bottom of the panel, and click New.

  3. The Mapping Editor window that displays is divided into left and right functional areas:
    • On the left, you add categories and relationships, and save or export your mapping.
    • On the right, you enter a Category Name (or Relationship Name), inspect Sample Data from the CSV, and specify the Properties to be mapped from the CSV ColumnName to a PropertyName for the current category or relationship. You’ll first create categories, then add relationships. The first category, shown as a circular icon labeled Category1, is automatically created and selected.

  4. On the right, in CategoryName, change the label to Image.

    NOTE: A standard naming convention for categories and relationships will make mappings and your graph data more readable. For example, capitalize category names (Image), and use upper case with words separated by underscore characters for relationship names (TAKEN_AT).

  5. Now add properties for the category. From the Sample Data area, click the the + (plus) icon next to columns to be included as properties. Each column name appears in the Properties list as you add it. A property will be named as in the CSV file, but you can enter a different name. If you add a property by mistake, simply click its trash can icon in the Remove column.

  6. Click the AsKey checkbox to set one or more properties as key values. In this example, we set the pkey_photo property as the key, ensuring that there will be only one node for each unique photo. Notice that you can set AsKey for more than one property, which provides flexibility in how you define unique entities in your mapping.

  7. Click the + (plus) icon again at the upper left to add a Rating category. Click to add the Rating column from the CSV as a property , and click to set it AsKey so that there will be a single node for each unique rating.

  8. Now click the + (plus) icon at the upper left to add the Author category. Click to add the Provider column as a property, rename it to authorName, and click AsKey so that there will be a single node for each unique photographer.

  9. Now add the directed dynamic relationships. Click the Add Edge icon on the upper left and click the source category (Image). Then click the second, target category (Rating). The relationship appears as an arrow between the two categories. The default name is the combined names of the two categories (Image_Rating). Since we want a dynamic relationship, edit Relationship Name to RATED_AT_{Rating}. Optionally, properties can be added to the relationship, but here we don’t need to.

    NOTE: A name you enter in the curly braces must exactly match the column header name in the CSV. If the Mapping Editor can’t match the name (for example, because it is misspelled), the relationship will be created, but will be labeled “undefined”.

  10. Now click the Image and then the Author category icons to add a dynamic TAKEN_BY_{Provider} relationship between the Image and Author categories.

  11. Click any category or relationship icon to review and make any changes.

  12. Click the Save As icon in the Mapping Editor window.

  13. In the dialog box, enter a name in the Save As text field, and click OK.

  14. The name appears in the Mapping dropdown menu. Click Apply to apply the mapping to the loaded file and import the mapped data.

  15. GraphXR queries the CSV, maps the data, and loads it to the project space.

Editing a mapping

You can edit the mapping at any time and Save it, or use Save As to edit and save as a new mapping. A CSV will still be loaded, so during the editing process, a mapping can easily be edited and then re-applied.

To edit a mapping:

  1. Open the CSV tab in the Query panel, click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

  2. Select the mapping you want to edit from the Mapping dropdown menu and click Edit.

  3. Edit, add or delete categories, relationships, and their properties.

  4. Click either the Save As icon to save your work as a new mapping, or the Save and Exit icon to save to the existing mapping.

To exit the editor without saving changes, click the X at the upper right of the Mapping Editor window.

Exporting or Importing a mapping

You can export a mapping as a JSON file, and then re-import it whenever you want.

It is good practice to export mappings before you exit a project.

To export a mapping as a JSON file:

  1. Open the CSV tab in the Query panel, click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

  2. Select the mapping in the dropdown menu, and click Edit to open the Mapping Editor.

  3. Click the Export Schema icon at the top left.

    A JSON file for the mapping is written to your local machine.

To import a mapping saved as a JSON file:

  1. Open the CSV tab in the Query panel, click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

  2. Click Import, navigate to the JSON file, and click Open.
    The mapping appears in the Mapping menu.

  3. Select the mapping and click Apply to query the loaded CSV data.

If you choose a mapping that was not defined on the CSV file you loaded, the following message displays: "Mapping not compatible with the data."

Deleting a mapping

You can delete any or all of the mappings for a given CSV.

To delete a mapping:

  1. Open the CSV tab in the Query panel, click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

  2. Select the mapping you want to delete from the Mapping menu and click Delete.