Use the Cache Files SDK Method (Tutorial)

	Abbreviations Key
HISE	Human Immune System Explorer
hp	hisepy
IDE	integrated development environment
SDK	software development kit
pd	pandas
UUID	universally unique ID

At a Glance

This document explains how to use cache_files() (Python) or cacheFiles (R) to download HISE files and store them in your IDE’s cache directory. If you have questions, contact Support.

Method signature

hp.cache_files(
    file_ids: list = None,
    query_id: list = None,
    query_dict: dict = None,
)

cacheFiles(
  fileIds = NULL,
  queryId = NULL,
  query = NULL
)

Parameters

The parameters for this method are listed in the following table. In each key:value pair, the value must be of type list.

Description

This function downloads HISE files and stores them in your IDE’s cache directory when you pass in one of the following:

• A list of file IDs (Python: file_ids | R: fileIds)
• A saved search ID (query_id | R: queryId)
• A custom search query (query_dict | R: query)

Unlike read_files, the cache_files method doesn't load files into memory. Instead, it makes them locally available and returns a list of file paths (strings) indicating where each file was downloaded in your local cache directory. Files are downloaded to your IDE's /input directory. The exact paths are returned by the function.

Logging and error handling

For transparency and reproducibility, cache_files automatically logs downloaded file IDs and sample IDs. If a file fails to download, an error message is printed to the console (e.g., "Error downloading file: <error message>"), and the function continues to process the remaining files. Failed file downloads are logged but don't interrupt the caching operation.

Instructions

The following instructions are written for Python. To adapt them for R, use the R function signature and parameters listed above.

 Import libraries

To get started, set up your environment to interact with HISE programmatically and access all available SDK functions. For details, see Use Hise SDK Methods and Get Help in the IDE.

1. Navigate to HISE, and use your organizational email address to sign in.

2. Open an IDE. For instructions, see Create Your First HISE IDE (Tutorial).

3. For programmatic access to HISE functions and efficient handling of tabular data, import the Python SDK and the pandas library.

# Import hisepy and pandas
import hisepy as hp
import pandas as pd

 Define file IDs

In this step, we define the file IDs for this notebook. For details, see Use Advanced Search (Tutorial).

1. Retrieve your own set of file IDs, and then define them as shown below. (The example below uses placeholder UUIDs—replace them with your own.)

# Define the file IDs used in this analysis 

FILEIDS = ['f805c067-7919-46a8-b3b4-a4461b12a279']

Download files to your cache

1. To download the file(s) and store them in your local directory, pass in the list of file IDs. 

# Cache files locally by file ID

hp.cache_files(file_ids=FILEIDS)

The following output is returned.

Verify the cache operation (optional)

1. To can confirm that the cache_files operation was successful, inspect your local HISE cache directory to see the downloaded files. Cached files are stored in /input and organized under subdirectories by dataset, file type, and file ID. The actual file contents are inside the <file_id> directory:

/input/<workspace_path>/<dataset_or_project_id>/<file-type>/<file_id>

 Create a DataFrame from your cache output (optional)

You can convert a list (such as a list of dictionaries or objects) into a structured, tabular data format that’s easy to work with using pandas. 

1. To collect your cache data, run the following command.

# Fetch the cache output

cache_output = hp.cache_files(file_ids=[`f805c067-7919-46a8-b3b4-a4461b12a279`]

      2. To create a DataFrame from your cache output, run the following command.

# Import pandas as pd and convert cache output to a tabular format

df = pd.DataFrame(list(cache_output))

4. To confirm the DataFrame creation, run the following command. You should see the data in a tabular (rows and columns) format, confirming that your cache output was correctly converted. 

# Print DataFrame to verify data structure

print(df)

Related Resources

Query SDK fileType

Create Your First HISE IDE (Tutorial)

Use HISE SDK Methods and Get Help in the IDE