Add Searchable Metadata to Project Store Files (Tutorial)

Last updated 2026-08-10

At a Glance

Make files in your Project Store easier to find when you or other HISE users search for them later. Add meaningful metadata—such as panel and batch IDs, custom tags, and linked samples—so search results provide the experimental context needed to identify the right file.

Use this function as part of an automated workflow to add searchable metadata after your code uploads, creates, or processes a file in a Project Store. For example, tag a processed image with its panel ID, batch ID, and sample references so collaborators can find it by searching for those attributes.

When to Use This Feature

Use this feature when you need to find Project Store files using metadata, rather than relying only on file names or folder locations.

For example, use it to do the following:

Help collaborators find files associated with a specific panel, batch, or sample
Add descriptive tags that distinguish files with similar names or contents
Connect derived files, such as processed images or analysis outputs, to their source samples
Update metadata after experimental details change or become available
Make a collection of files more consistent and easier to search across a Project Store

Method Signature

The signature for this method is listed below. Click the tabs to toggle from Python to R.

Python signature

hp.set_file_metadata_in_project_store(
    store_name: str,
    file_name: str,
    fields_to_set: dict,
    replace_where_multiple: bool = False,
)

Example

hp.set_file_metadata_in_project_store(
    store_name='my_project_store',
    file_name='my_file.txt',
   fields_to_set={
        'panelId': 'panel_123',
        'batchId': 'batch_456',
        'userTags': {'processingStage': 'processed_data', 'qualityStatus': 'quality_checked'},
        'sampleReferences': ['sample_1', 'sample_2']
    },
    replace_where_multiple=True
)

R Signature

setFileMetadataInProjectStore(
  storeName,
  fileName,
  fieldsToSet,
  replaceWhereMultiple = FALSE
)

Example

hp$setFileMetadataInProjectStore(
  storeName = "my_project_store",
  fileName = "my_file.txt",
  fieldsToSet = list(
    panelID = "panel_123",
    batchID = "batch_456",
    userTags = list(
      processingStage = "value1",
      qualityStatus = "value2"
    ),
    sampleReferences = list("sample_1", "sample_2")
  ),
  replaceWhereMultiple = TRUE
)

Parameters

The parameters for this method are listed in the following table. Click the tabs to toggle from Python to R.

Parameter	Data type	Required or optional	Description
`store_name`	`str`	required	Name of Project Store
`file_name`	`str`	required	Name of file
`fields_to_set`	`dict`	required	Dictionary containing the fields to set. Possible keys are `panelId`, `batchId`, `userTags`, and `sampleReferences`. The `panelId` and `batchId` should be strings, `userTags` should be a dictionary, and `sampleReferences` should be a list of sample references.
`replace_where_multiple`	`bool`	optional (default: `False`)	If `True`, replaces existing values in fields that support multiple values. If `False` (default), appends the provided values to existing values.

`storeName`	`str`	required	Name of Project Store
`fileName`	`str`	required	Name of file
`fieldsToSet`	`dict`	required	A named list of metadata fields and their value. Current valid fields are "panelID" (character vector), "batchID" (character vector), "userTags" (a named list of searchable tags, as tag name => value, for which the following tag names are valid: ["version", "name", "details", "group", "origin", "other"]), and "sampleReferences" (a list of HISE sample UUIDs). Not all of these fields need to be included.
`replaceWhereMultiple`	`bool`	optional	A boolean that determines whether fields with multiple values should have their existing values replaced by the provided list (if `TRUE`), or just appended to (if `FALSE`). Defaults to appending to the existing values.

Instructions

Specify the file to update

Set the Project Store name and the name of the file whose metadata you want to update. In most workflows, your code already has these values from an earlier file-creation or processing step or from an earlier upload.
```
store_name = "my_project_store" 
file_name = "my_file.txt"
```

Create the metadata dictionary

Using the metadata you want to add or update, create a fields_to_set dictionary. Include only the fields that apply to the specified file. Choose among the exact field names specified here so the method can apply the metadata correctly:
- panelId for a panel identifier
- batchId for a batch identifier
- userTags for searchable tags, supplied as a dictionary
- sampleReferences for a list of sample references
```
fields_to_set = {
    "panelId": "panel_123",
    "batchId": "batch_456",
    "userTags": {
        "processingStage": "processed_data",
        "qualityStatus": "quality_checked"
    },
    "sampleReferences": [
        "sample_1",
        "sample_2"
    ]
}
```

Update and apply the file metadata

Call hp.set_file_metadata_in_project_store() with the file information and metadata dictionary. To replace a field's existing values when it has multiple values, set replace_where_multiple=True. Otherwise, omit this argument to use its default value of False.
```
response = hp.set_file_metadata_in_project_store(
    store_name=store_name,
    file_name=file_name,
    fields_to_set=fields_to_set,
    replace_where_multiple=True
)
```

After the metadata is updated, you and other users can search HISE using the panel ID, batch ID, user tags, or linked sample references to locate the file.

Related Resources

Understand Watchfolders and the Project Store

Ingest Data into the Project Store (Tutorial)

Use Specified Metadata Models (Tutorial)