The File Query feature inside a job run allows administrators to obtain detailed information about the files in a specific job. This user guide provides step-by-step instructions on how to use the File Query functionality efficiently.
Configuring and running the Query
Admin can launch a query in a Synchronization job, or in active job runs of Distribution or Consolidation jobs.
On the File Query tab, click "Find" button to open configuration dialog. A user with "View-Only" access to the job can launch the query.
Select the Agents on which the query will be launched. Offline Agents cannot perform the query.
Select the query parameters.
A maximum of 1000 files can be returned in the results.
Once configured, the query is performed by the Agents. The default timeout for query is 30 minutes and can be configured in MC Settings -> General -> Advanced settings.
Query by path
Use this query to learn about a specific file. Give the path to the file (not subfolder) in the job, relative to the job directory. Full paths are only supported if the Agents are on the same operating system. For network shares only UNC paths are supported.
Cloud storage paths are supported.
When querying by path, the Agent will check the file's state on the storage by given path and return the result. Regular expressions are not supported in this query
Query by status
Use this query to learn about files' state in Agent's database. Select the statuses for query. It's possible to set a filter for files in the results with a regular expression. The Agent will report the file's status based on its internal database. Agent will not check the real state of the file on the storage.
Downloaded: Files is synced with other online Agents in the job. This status includes the pre-seeded and locally copied files.
Can't be synced now: Files are not synced. There's a problem with the file as reported in Info column.
In queue now: File is being synced or in in queue to be synced. This status does not included Ignores files, placeholders, or files invalidated on RO Agents.
Deleted: shows the files that were removed from disk within the given period.
It's possible to filter the results by file name pattern. Regular expressions are supported in this filter.
Understanding the query results
Generally, the Agent returns the current state of the files for the given moment. Results do not contain history of file changes.
Query results contain the Agent that performed the query, files status on this Agent, some detailed information, files size and timestamp, and additional information from the database. Generally, the results are self-descriptive, however, there are a few peculiarities highlighted below.
Query by path
In this query the Agent will check the file by the given path. In the results in column "Status" it will show the status that Agents has in its database and additionally in Info its state on disk (what the Agent has read about this files from the storage or a system error).
Sometimes, the results may even seem contradicting, especially if the Agent didn't add this file to its database. For example, if the file is in 'File and folder filter", the Agent may return status "unknown" because it didn't add it to the database, but the file is present on disk. In the example below, Helenlatop Agent didn't add the file to database and didn't upload the pdf file because it's ignored. Therefore, the other Agent doesn't even know about it.
Placeholders in TSS shares also report some state on disk - size and timestamp. However, macOS Agents and some Windows Agents in TSS share may return "file not found" info for placeholders.
Querying symbolic links depends on setting "Follow symlink" in the Profile. If it's No, the agent will not follow the link and will report the status "unknown." If the setting is Yes, the Agent will return the information about the file by this link.
When querying by a full path, keep in mind that some Agents won't be able to resolve this path and will report 'no files found.
Query by status
Selected statuses are united with OR. In this query the Agent will return the information from its database not checking the files state on disk.
Status "In queue now" may show Info with percentage of downloaded file if the file is being actually downloaded now or has been partially downloaded; or "Agent will download this file later" which means that the file is in queue but is not being downloaded right now.
For deleted files, the Time column shows time of deletion. For other status - file modification time.
If the file is deleted on a non-deleting Agent, the corresponding Info will appear informing that this deletion was not propagated to remote Agents.
Files there were deleted or changed on source Agent in Distribution or Consolidation jobs will be in status "can't be synced now" with Info about file changes.
Query errors
Offline Agents and Agents of older version will not perform the query at all.
In certain cases it's known that the Agents are not synced with each other, for example, they are not connected to each other, or they are on pause, or have excessive time difference with each other. However, they can know something about the files they have, but they cannot guarantee that this is the latest possible status of the file. The query will inform admin that query results might be imprecise.
Query results can be exported in csv format.
Saving and Storing Queries
The File Query results are stored by Management Console in special databases for 30 days by default. It can be changed in MC configuration file.
For Distribution and Consolidation job runs the query results are saved only for the active job run or only one completed job run.
Peculiarities and known limitations
- A single Agent in the job cannot show ignored files.
- Searching by the "info" column may not always return expected results, especially when searching by file owner's name or ID.
- Zero-sized files are counted as regular files for all statuses.
- macOS Agents and some Windows Agents in TSS share may return "file not found" info for placeholders
- Query by name won't work for files that have backslash in their names. Use query by status with filter for such files.
-
Query by name for files with Unicode symbols may return invalid results. Use query by status with filter for such files.
- Regular expressions in File filter do not support backslash (\d \w \W \s , etc). Use [0-9] [a-zA-Z] instead.
- Agents' service folder .sync can be queried by path, but is reported to be Ignored.