Pre-Hydrate Files into TeamCache

Target audience: Workspace administrators

Overview

Pre-hydration loads files into TeamCache before anyone opens them. Normally a file is cached the first time someone reads it, which means the first person to open it waits for the download from the cloud. Pre-hydration moves that wait to a time you choose.

Use it when you know in advance what your team will need: a project that starts tomorrow morning, a media library handed over from another site, or a cache that was recently restarted and is still cold.

Frequently Asked Questions

Do I need to pre-hydrate data that was written by a user actively using TeamCache? No. Any read through the cache stores the file, so the cache fills on its own as your team works. Pre-hydration only moves that work earlier.

Who can pre-hydrate? Pre-hydration requires at least filespace admin permissions.

What path do I give it? A path relative to the filespace root, not a path on your local disk.

Can I pre-hydrate a whole folder? Yes. Pointing it at a directory pre-hydrates that directory and everything under it.

Do pre-hydrated files stay cached permanently? No – pre-hydrated entries are cached the same way normal reads are, with no pinning or prioritisation, so they are evicted under the same policy as anything else in the cache. Pre-hydrate close to when the work actually starts, and keep what you pre-hydrate smaller than the cache, or the earlier part of the job will be pushed out before anyone opens it.

What's the eviction order? Least-recently-used (LRU). TeamCache itself does not set an expiry on cached objects, so pre-hydrated files do not go stale and get silently refetched again.

Does pre-hydration download files to my own machine? No. It loads files into the shared TeamCache server so that everyone at that location benefits, not into your local client cache.

Before you start

TeamCache is installed and running. See Install and Set Up TeamCache
The client you run the command from has the cache address set. Confirm by running lucid config --effective and checking the value for TeamCache.Location.
You have filespace admin permissions.
For convenience pre-hydration may additionally be done from a dedicated LucidLink client on the TeamCache server itself.

Steps to pre-hydrate from the TeamCache server directly:

Install the LucidLink client on the TeamCache server. The TeamCache installer does not do this.
Link to the filespace on that server as a filespace administrator. The installer does not mount a filespace for you.
Set the cache address on the client so that the files it reads are stored in the cache: lucid config --set --TeamCache.Location <cache-address>
Run the pre-hydration commands from the TeamCache server rather than from a workstation.

Pre-Hydrating from the Command Line

Pre-hydrate a single file:

lucid team-cache --pre-hydrate path/to/file.txt

Pre-hydrate a directory and everything inside it:

lucid team-cache --pre-hydrate path/to/directory

Paths are relative to the root of your filespace.

Pre-Hydrating from the context menu

On Windows and macOS, right-click a file or folder inside your filespace and choose Prehydrate in TeamCache.

Pre-hydration from the context menu is functionally identical to doing it from the command line.

Checking job status

List the pre-hydration jobs that are currently running:

lucid team-cache --pre-hydrate --list

Each job reports one of the following states:

State	Meaning
`InProgress`	Files are being loaded into the cache.
`Completed`	All files were cached successfully.
`Failed`	The job did not complete. Most often because the storage or the filespace hub couldn’t be reached in time. It can also happen if a newer pre-hydration request targets the same or an overlapping path while the first is still running.

Troubleshooting

A job reports Failed: The job did not complete. Most often because the storage or the filespace hub couldn’t be reached in time. It can also happen if a newer pre-hydration request targets the same or an overlapping path while the first is still running.
The command is rejected or returns a permission error: Pre-hydration requires filespace admin permissions and TeamCache that is enabled and configured. Make sure that TeamCache is enabled: lucid config --hidden should show 1 for TeamCache.Enabled, and also that TeamCache is configured: lucid config --effective should show the address for the cache for TeamCache.Location. Then make sure to run the pre-hydration commands as a user that has filespace admin permissions.