Atlas: How to Configure Relationship Mapping

We get it: databases are messy. They're littered with bad decisions, good decisions, no decisions, and indecisiveness.

With that in mind, Ethyca created Atlas Relationship Mapping, designed to intelligently and automatically access and update the information in your hosted databases.

If you've dealt with SQL databases, you're no stranger to the concept of primary key and foreign key. Ethyca created its own construct for how to think about relationships between data as it pertains to accessing and removing data related to a data subject's identity. The Atlas PII (Personally Identifiable Information) mapping exercise creates a "PII graph", which lays out linked entities and relationships throughout your database schema(s).

There are 5 key relationship concepts to keep top of mind as you go through your PII mapping exercise in Atlas 1.5+:

1. Primary ID or key(id)

As with traditional primary key relationships, the id is the primary key column of the table. It should be unique and NOT contain personally identifiable data. It is important to note that this field will never be deleted in an erasure request because an ID on its own generally is not considered PII.

name: "user_table"
  properties:
  name: "id"
   datatype: "integer"
   data_attribute: "id"

2. Primary Subject Identity(identity)

This is where it all begins: the subject's identity. This is how we identify the human user who entered the data subject request, and how we trace where and how the data has flowed throughout your database schema to create a PII "graph". We almost always use the email address as the subject's identity.

- name: "user_table" 
  properties:
 - name: "id"
   datatype: "integer"
   data_attribute: "id"
 - name: "email"
   datatype: "varchar"
   data_attribute: "identity"

3. Secondary Subject Identity (ref_identity)

In the event that a subject's identity can be found in a table that you would not want to create a PII graph from, such as a "Referred by" field, or "Emergency Contact" field, you would indicate "referredby" as Secondary Subject Identity (or ref_identity, if using yaml). Not creating the PII graph means that we will not follow these linkages to other tables.

name: "user_table" 
  properties:
   name: "id"
   datatype: "integer"
   data_attribute: "id"
...
  name: "referredby"
   datatype: "varchar"
   data_attribute: "ref_identity"

4. Foreign key (ref_id)

As in traditional foreign key relationships, we have an orders table that is linked to a user through the user table's primary key. We would indicate userid as a "foreign key" (or ref_id if using .yaml) pointing toward the user_table. Using this relationship, Atlas will both retrieve and delete for all orders where the userid is a match.

entities:
 name: "orders_table"
  properties:
    name: "id"
    datatype: "integer"
    data_attribute: "id"
...
    name: "userid"
    datatype: "integer"
    data_attribute: "ref_id"
    referenced_type: "user_table"

5. Foreign key to shared resource (ref_immediate)

In this case, we are referring to a traditional foreign key relationship where we would never want to delete information from the foreign table. In the example here, the user_table calls out to a shared_address_table. Because other tables may rely on the shared_address_table as a shared resource, you probably don't want to delete things from it. Using this relationship, Atlas will ONLY retrieve and NOT delete addresses where the address ID from the user_table is a match.

name: "user_table" 
  properties:
   name: "id"
   datatype: "integer"
   data_attribute: "id"
...
   name: "addressid"
   datatype: "varchar"
   data_attribute: "ref_immediate"

ℹ️ Important note: Not every column will have a relationship mapping! These relationship mappings are used pretty sparingly, but they help us to create your PII graph accurately.

Support

Please contact [email protected] or your dedicated Customer Success Manager if you require any technical assistance for the installation or configuration of Ethyca's Atlas or if you're at any point unsure about whether to identify a column with a relationship.