(howto) Overwrite and delete data from the data model

This doc is in progress. Feel free to leave feedback on how it can be improved.

Overwrite

If an attribute already exists, you can import a load file to overwrite its values.

For example, you may have previously imported a participant load file that had several columns of metadata. If you import another participant load file, it will overwrite values in all columns that existed in the previous load file, and create new entries for any new columns.

Delete

To delete data entities or attributes from your workspace, you'll need to use the FireCloud API, as the delete functionality is not available through the web interface.

See below a step by step example of how you would delete a sample from a workspace or delete an attribute of a sample (or other entity) using the API Swagger page. If you're not familiar with this, Swagger is a popular web interface for making APIs user-friendly. You can use the API commands directly from that web page by filling in the various text fields; or you can also run the corresponding commands shown on the page from your terminal.

Before you do anything else inside a selected endpoint, you need to authenticate yourself in the Swagger page. If you see a red circle with the exclamation mark in the top right corner of the colored area, click on it (if you don't see one, congratulations, skip this step).

In the dialog that opens up, check the box that says "openid" and click the "Authorize" button. This will make you authenticate through your Google account profile. Once that's done you'll be back on the API page and the red circle should be blue.

How to delete one or more Sample_Id(s), Participant_Id(s), Pair_Id(s) or Set_Id(s)

1. Go to the API Swagger page. On that page you'll find a list of all the "endpoints", which correspond to the possible commands you can run. Click here for a direct link or find POST /api/workspaces/{workspaceNamespace}/{workspaceName}/entities/delete.The line will expand to reveal input text fields along with example values and some description of what this does.

2. Fill in the namespace (the first part of the workspace name ending at the forward slash) and name of the workspace from which you want to delete the entity in the corresponding text fields.

3. Next, the body field is where you specify which entity you want to delete. If you click on the box with the example values on the right, it will automatically copy the contents over to the input field, then you just need to fill in the values. Replace string with the relevant text for entityType and entityName.

• For example, to delete a specific sample ID, the entityType will equal sample and the entityName will be the ID of that sample from the sample_ID column. To delete multiple entities, copy and paste the json format with a comma in between:

  [
    {
      "entityType": "sample",
      "entityName": "NA12878_24RG_small"
    },
    {
      "entityType": "sample",
      "entityName": "NA12878_24RG_med"
    }
  ]
  

4. Then find the little button labeled "Try it out!" and click. If everything worked correctly, the box will unfold further and among other things, there will be a line that says the result code is 204 for Successful request. A 409, means the entity you tried to delete has other entities that depend on it. For example, a sample that is contained in a sample set cannot be deleted unless you also delete the sample set. A 0 response code or “no server response” can be resolved by logging out your “openid” and logging back in.

How to delete an attribute of a Sample_Id(s), Participant_Id(s), Pair_Id(s) or Set_Id(s)

1. Go to the API Swagger page. On that page you'll find a list of all the "endpoints", which correspond to the possible commands you can run. Click here for a direct link or find PATCH on /api/workspaces/{workspaceNamespace}/{workspaceName}/entities/{entityType}/{entityName}.The line will expand to reveal input text fields along with example values and some description of what this does.

2. Fill in the namespace (the first part of the workspace name ending at the forward slash) and name of the workspace from which you want to delete the attributes.

3. Specify the entity type (participant, sample, pair, set) and the entity name (specific id).
4. Next in the ‘attributeupdateJson’ section click the box on the right with the example values. This will automatically copy the contents over to the input field. You just need to add square brackets [ around the request ] and fill in the values. For “op”, operation, type “RemoveAttribute”. Then list the name of the attribute (the column header) you’d like to remove in “attributeName.” Replace string with the relevant text.

Example of removing the Zipcode (attributeName) from a sample, participant, pair, or set.

[
  {
    "op": "RemoveAttribute",
    "attributeName": "ZipCode"
  }
]

5. Then find the little button labeled "Try it out!" and click. If everything worked correctly, the box will unfold further and among other things, there will be a line that says the result code is 204 for Successful request. A 409, means the entity you tried to delete has other entities that depend on it. For example, a sample that is contained in a sample set cannot be deleted unless you also delete the sample set. A 0 response code or “no server response” can be resolved by logging out your “openid” and logging back in.

In addition, there are other “ops” with examples listed below:

AddUpdateAttribute: create a new attribute called attributeName with the attribute value addUpdateAttribute on the entity

i.e. you want to add a Zip Code attribute to an entity:

[
  {
    "op": "AddUpdateAttribute",
    "attributeName": "ZipCode",
    "addUpdateAttribute": "90210"
  }
]

AddListMember: add a value newMember to the list attributeListName on the entity. This will create an array of values.

i.e. you want to have an attribute list of Zip Codes that the person (sample) has ever lived in. Each entry is another member of the list you want to add [90210, 90211]:

[
  {
    "op": "AddListMember",
    "attributeListName": "ZipCodes",
    "newMember": "90210"
  },
  {
    "op": "AddListMember",
    "attributeListName": "ZipCodes",
    "newMember": "90211"
  }
]

RemoveListMember: remove a value removeMember from the list attributeListName on the sample, participant, pair, or set.

i.e. you want to remove one of the Zip Codes from that list because you realized it was wrong:

[
  {
    "op": "RemoveListMember",
    "attributeListName": "ZipCodes",
    "removeMember": "90211"
  }
]

CreateAttributeEntityReferenceList: create an empty list attributeListname of references

i.e. creates a new column called Reference_List and will display 0 items in the list.

[ 
 {
    "op": "CreateAttributeEntityReferenceList",
    "attributeListName": “Reference_List”
  }
]

CreateAttributeValueList: create an empty list attributeListname.

i.e. creates a new column called ZipCodes and will display 0 items in list.

[ 
 {
    "op": "CreateAttributeValueList",
    "attributeListName": "ZipCodes"
  }
]