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 categories, properties, relationships, and key values you specify. Once you create a mapping, you can:

  • Save, apply, and edit the mapping.

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

Creating a Mapping

We’ll start with an example CSV file that contains a list of photographic images and includes metadata such as photographer, image ID, size, keywords and ratings, and location (place names and latitude-longitude).

The same basic process applies to creating a mapping for a table in an SQL relational database.

To begin with, we want to see the locations on a map, to understand how many photos and authors we have for each place. We can load the CSV table in the query panel, and then create and apply a simple mapping of the data as shown below:

  • Photos, Location, and Author categories with appropriate properties:

    • Photos can include the pkey (since we have one), photo ID number, name, url, image size, date taken, provider, copyright, rating.

    • Author can include provider.

    • Place can include the region pkey, region ID, place name, latitude and longitude, state, and country.

  • TAKEN_AT and CREATED relationships between the categories.

Any mapping can easily be edited and then re-applied.

To create a mapping:

  1. In the Query panel, open the CSV tab.

  2. 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, and the contents of the file including its column headings are displayed in a data table, 10 records at a time.

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

  4. The Mapping Editor window displays.

    It 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.

  5. You’ll first create categories, then add relationships. The first category, shown as a circular icon labeled Category1, is automatically created and selected. On the right, in CategoryName, change the label to Photos.

  6. 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.

  7. 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.

  8. Now that the first (Photos) category is defined, click the + (plus) icon at the upper left to add another category (for Author). We’ll just add the provider column as a property, rename it to authorName, and click AsKey to ensure that we only have a single node for each unique photographer.

  9. Click the + (plus) icon again at the upper left to add the third category (for Location). We’ll add properties relating to the location where a photo was taken, such as the place name, latitude, longitude, and altitude. We’ll set AsKey for pkey_region. Notice that you can set AsKey for more than one property, which provides flexibility in how you define unique entities in your mapping.

  10. Once at least two categories are created, we can add a relationship. Click the Add Edge icon on the upper left and click the source category (Photos). Then click the second, target category (Location) to create the directed relationship, which appears as an arrow between the two categories. The default name is the combined names of the two categories (Photos_Location).

  11. Edit Relationship Name (e.g. to TAKEN_AT). Optionally, you can add one or more properties and choose a key property. In this case we don’t need to.

  12. Repeat the process to add a CREATED relationship between Photos and Author categories. In this case we’ll add the Rating property to the relationship (but not set it as a key).

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

  14. Click the Save and Exit icon in the Mapping Editor window, enter a name in the Save As text field, and click OK.

    The name appears in the Mapping dropdown menu.

  15. Click Apply to apply the mapping to the loaded file and import the mapped data. GraphXR queries the CSV, maps the data to your graph model, and loads it to the project space.

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).

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.

To edit a mapping:

  1. Open the CSV tab in the Query panel.

  2. Click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

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

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

  5. 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.

  2. Click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

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

  4. 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.

  2. Click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

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

  4. 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.

  2. Click Load CSV, navigate to the CSV file associated with the mapping, and click Open.

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