Loading...

XML Query Examples for the File Level Analytics Report on the Command Line

The following XML queries are examples that can be used for the Command Line Version of the File Level Analytics Report.

Browsing Files in One Directory

This browse query is the simplest one, providing a basic building block upon which to build more complex queries. It presents the minimum required XML to run a query. As with Browse operations on the CommCell Console, this query returns the contents of one directory. Unlike the Find operation, Browse is not recursive. It does not traverse any folders that may be contained in the path folder that you specify; it only returns metadata for the files and folders contained in it.

To run this query, follow the steps described in General Procedure, using the browse_files_template.xml file.

Important

  • Folders are also returned with the file results, with a dataResultSet size attribute of size="0".
  • Archived files return the size of the actual file, not the stub.

Example

This example of the XML for this query shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs"/>
    <queries type="DATA"/>
    <mode mode="2"/>
</databrowse_BrowseRequest>

You can modify the results this query returns by adding more elements to the XML. These elements are described in the sections that follow, as they are introduced. A list of all the available elements is provided in Supported Elements and Parameters Used in Index Queries. The XML structure that supports those optional elements is described in the sections that follow.

Browsing for Files Larger than a Size You Specify

This XML template returns the names of all the files in one folder that meet size criteria you enter into the XML by adding a whereClause parameter to the queries element.

To run this query, follow the steps described in General Procedure using the browse_files_by_size_template.xml file.

Example

This example of the XML for this query shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs"/>
    <queries type="DATA">
        <whereClause connector="AND">
            <criteria field="FileSize" dataOperator="GT" dataUnits="KB">
                <values val="20"/>
            </criteria>
        </whereClause>
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>

The whereClause element and its sub-elements (criteria and values) let you specify values to filter on and what tests to apply. In the example given above, some elements have been added to the basic Browse Files example given above. These include:

  • <whereClause>, which opens a place in the structure where you can enter testing criteria.
  • <criteria>, where you specify the file metadata field to test, the kind of test, and the units to apply to the value.
  • <values>, for specifying the value to test the field against, using the operator and units in the <criteria> element.

See Supported Elements and Parameters Used in Index Queries for more information on these elements and the supported values for them.

Important:

  • Folders are also returned with the file results, even though their dataResultSet size attribute is size="0".
  • Archived files filter on the size of the actual file, not the stub size.

Finding Files

This basic XML template returns an unfiltered list of files, starting at the path folder. This query uses the Find value for opType, which can work recursively (starts at the path folder that you specify, descending into all subdirectories until the entire tree from your starting point downward has been traversed). The output supplies the complete path to each file or folder returned.

To run this query, follow the steps described in General Procedure, using the find_files_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="\**\*"/>
    <queries type="DATA">
    </queries>
</databrowse_BrowseRequest>

The primary difference between this example and the first example (Browse Files in One Directory) is the use of the Find value for opType (which supports recursive searching) and the path value (which supports wildcards when used with the Find opType). The double wildcard shown shown in the example requests recursive searching. See required parameters for details on the path value in Find operations.

Like all of these examples, you can take this template and add more XML to it or change its values to alter its behavior. See Supported Elements and Parameters Used in Index Queries for more information.

Finding Files in Multiple Paths

To search multiple, independent paths in a single query operation, specify more than one <paths> element in a Find operation. The standard rules for wild card usage for Find operations apply to this query, which returns an unfiltered list of files, starting at each path folder, and recurring if you have used a double wildcard (see the second paths element in the example).

To run this query, follow the steps described in General Procedure, using the find_files_multi_path_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="\Users\Administrator\Documents\*"/>
    <paths path="\Users\jsmith\Documents\**\*"/>
    <queries type="DATA">
    </queries>
</databrowse_BrowseRequest>

This example returns information for files and folders contained in the Documents folders for the two users named in the paths (Administrator and jsmith). Note that this Find operation is not recursive for the Administrator account, but is recursive for the jsmith account, because of the recursive wildcard pattern, "\**\*" used for the jsmith path. You can put as many <paths> elements as you need.

Finding Files in a Size Range

This query traverses the directory tree, starting at the path folder, and returns a list of files larger than a minimum size, but smaller than a maximum size.

To run this query, follow the steps described in General Procedure, using the find_files_in_size_range_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\**\*"/>
    <queries type="DATA">
        <whereClause>
            <criteria field="FileSize" dataOperator="GT" dataUnits="KB">
                <values val="10"/>
            </criteria>
        </whereClause>
        <whereClause connector="AND">
            <criteria field="FileSize" dataOperator="LT" dataUnits="KB">
                <values val="50"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

This example builds on the above Find Files example by adding of two whereClause structures to perform the filtering on file size. The additional parameter on the second whereClause element, connector="AND", defines the relationship between the two where clauses, AND requiring that both conditions must be met. The value for dataUnits can be any of the values supported for this parameter, listed in Supported Elements and Parameters Used in Index Queries.

Important:

  • Unlike Browse operations, Find operations do not return paths that end at folders, but do return their contents.
  • Archived files filter on the size of the actual file, not the stub size.

Finding Folders in a Size Range

This XML template returns a list of all files in folders that fall between two folder sizes (in this example, larger than 10 megabytes, but smaller than 35 megabytes). Because this query uses the Find value for opType, it works recursively. It returns metadata for all folders found.

To run this query, follow the steps described in General Procedure, using the find_folders_in_size_range_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc1" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="F:\data1\data"/>
    <queries queryId="0" type="DATA">
        <whereClause>
            <criteria field="FolderSize" dataOperator="GT" dataUnits="MB">
                <values val="10"/>
            </criteria>
        </whereClause>
        <whereClause connector="AND">
            <criteria field="FolderSize" dataOperator="LT" dataUnits="MB">
                <values val="35"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

The primary difference between this example and the one for finding files in a size range is the use of "FolderSize" for the criteria value.

Important: Although the where clauses do filter on folder size, the size indicated in the returned results (dataResultSet size) is 0 (zero).

You can modify the behavior of this query by changing some of its values in the XML, such as changing the value to dataUnits="KB" to test for file size in kilobytes rather than megabytes. See Supported Parameters Used in these Queries.

Finding Files by Modification Date

This query traverses the directory tree, starting at the path folder, and returns a list of files that were modified on or after a certain date.

To run this query, follow the steps described in General Procedure, using the find_files_modified_after_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\**\*"/>
    <queries type="DATA">
        <whereClause>
            <criteria field="ModifiedDate" dataOperator="GT">
                <values val="1399420800"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

This example uses the whereClause structure to filter on a file modification date. The value you enter for ModifiedDate is the number of seconds since January 1, 1970 (that is, standard Unix timestamp format). Calculators are available on the Internet to convert between calendar time and Unix timestamp values. The output of this command also provides its date information in Unix format. Changing the GT to LT finds files modified before the timestamp date you enter, instead of after.

Finding Files by Backup Date

You can filter on the date, or range of dates, that files and folders were backed up. As with the other queries that use opType=Find, this one works recursively if you specify recursion in the path element by using the double-asterisk notation, "**\*".

To run this query, follow the steps described in General Procedure, using the find_files_by_backup_date_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client2" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\xml_testing\*"/>
    <queries type="DATA">
    </queries>
    <timeRange>
        <fromTime>2014-08-27 00:00:00</fromTime>
        <toTime>2014-08-27 23:59:59</toTime>
    </timeRange>
</databrowse_BrowseRequest>

This example uses the timeRange structure to filter on the date when files or folders were backed up. A fromTime or a toTime parameter (or both) can be used. If using only one of these parameters, include the other parameter, but set it to 0. For example, to see files and folders backed up any time starting at August 27, 2014, use <fromTime>2014-08-27 00:00:00</fromTime> <toTime>0</toTime>.

Viewing Properties of a File

This XML template returns the metadata for a file in one folder that matches the file name you enter in the path. Because it uses the opType of Browse, this query only searches the path folder.

To run this query, follow the steps described in General Procedure, using the browse_files_like_name_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc1" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="F:\data1\data\test2\testa\testaa"/>
    <queries queryId="0" type="DATA">
        <whereClause connector="AND">
            <criteria field="FileName" dataOperator="LIKE">
                <values val="cvfwd.log"/>
            </criteria>
        </whereClause>
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>


This example makes use of the SQL "LIKE" operator for pattern matching. In this case, it is being applied to the fileName metadata field. Place the name of the file you are browsing for in the criteria...values...val field, where you see cvfwd.log in the example above.

Important: The LIKE function does not support using wildcards in these Commvault XML queries.

You can modify the some of the behaviors of this query by changing some of its values in the XML. See Supported Parameters Used in these Queries.

Finding Files Using Multiple Fields

As you would expect, you are not limited to using only a single field when filtering. This query traverses the directory tree, starting at the path folder, and returns a list of files that meet criteria for two different fields (modified after a certain date and larger than a specific size). This is sometimes called a "hybrid" query.

To run this query, follow the steps described in General Procedure, using the find_files_using_multiple_fields_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\**\*"/>
    <queries type="DATA">
        <whereClause>
            <criteria field="ModifiedDate" dataOperator="GT">
                <values val="1399420800"/>
            </criteria>
        </whereClause>
        <whereClause connector="AND">
            <criteria field="FileSize" dataOperator="LT" dataUnits="KB">
                <values val="50"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

This example uses two whereClause structures to filter on two different fields (file modification date and file size). Again, the value you enter for ModifiedDate is the number of seconds since January 1, 1970 (standard Unix timestamp format). The output of this command provides its date information in Unix format. And of course the dataUnits value can be any of the supported units listed under <criteria dataUnits> in the Supported Elements and Parameters Used in Index Queries table.

Finding Files Modified Yesterday

This XML template returns a list of file metadata, for files modified the previous day, starting at the path folder.

To run this query, follow the steps described in General Procedure, using the find_files_modified_yesterday_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc5" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\**\*"/>
    <queries queryId="0" type="DATA">
        <whereClause>
            <criteria field="ModifiedDate" dataOperator="IN">
                <values val="Yesterday"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

You may have noticed that you could actually get the same results by using the Find Files by Modification Date query, just by setting the modification date to yesterday's date. This form of query is provided to simplify that operation. See the values entry in the Supported Parameters Used in these Queries table to see the supported values for this form of date filtering.

You can also modify the behavior of this query by changing some of its values in the XML, such as changing the value to criteria field="ModifiedDate" to field="CreatedDate" to test for files that were created yesterday, rather than modified yesterday. Supported Parameters Used in these Queries provides a list of values supported by this test.

Getting a Count of Archived Files

This XML template returns a count of files that have been archived, recursively in folders starting at the folder you specify.

To run this query, follow the steps described in General Procedure, using the count_archived_files_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="indexingstorage_4" subclientName="sc5" backupsetName="scale_bkp" appName="File System" _type_="0"/>
    <paths path="\**\*"/>
    <queries queryId="1" type="AGGREGATE">
        <aggrParam aggrType="COUNT" field="FileName"/>
        <whereClause connector="AND">
            <criteria field="StubbedObject" dataOperator="IN">
                <values val="ShowOnly"/>
            </criteria>
        </whereClause>
    </queries>
</databrowse_BrowseRequest>

The result of this operation is a count of files that are in an archived state (that is, a count of stubs), recursively, starting at the path specified. It appears in the XML structure as <aggrResultSet result="5"/>, where the actual count of files is indicated where this example shows the "5".

You can modify the some of the behaviors of this query by changing some of its values in the XML, such as changing the value to dataUnits="KB" to test for file size in kilobytes rather than megabytes. See Supported Parameters Used in these Queries.

Output of This Query

This query, with its queries type of AGGREGATE produces a different output than the type=DATA queries documented on this page. The output is found in the aggrResultSet element, such as this example: aggrResultSet result="5", where 5 is the number of archived files found.

Browsing for the Largest Files in One Folder

As supplied, this XML template returns the names of the two largest files in a folder. This query, being based on the Browse operation type, is not recursive. It uses the SQL TOPBOTTOM function for its query type, which has parameters to control the data it returns.

To run this query, follow the steps described in General Procedure, above, using the browse_largest_files_template.xml file.

Example

Here is an example of XML for this query, showing sample values in the required parameters:

<databrowse_BrowseRequest opType="Browse">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\"/>
    <queries queryId="TOPBOTTOM" type="TOPBOTTOM">
        <topBottomParam ascending="" count="2" field="FileSize"/>
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>

In this example, the TOPBOTTOM parameters are set to ascending="", and count="2". Setting the parameters this way returns the two largest files in the folder. See Supported Parameters Used in these Queries for the parameter settings.

Output of This Query

This query, with its queries type of TOPBOTTOM does not include the version parameter in its output. The other parameters are the same as the queries that use type=DATA. (See XML Output.)

Listing the Available Versions of a File

This XML template returns a list of the available versions of a file, in the folder you specify (this query is not recursive).

To run this query, follow the steps described in General Procedure, using the list_versions_of_file_template.xml file.

Example

This example XML shows sample values in the required parameters:

<databrowse_BrowseRequest opType="Versions">
    <entity commCellId="2" clientName="doc_client" subclientName="default" backupsetName="defaultBackupSet" appName="File System" _type_="0"/>
    <paths path="C:\Users\Administrator\Documents\test_docs\create client steps log.txt"/>
    <queries queryId="0" type="DATA">
    </queries>
    <mode mode="2"/>
</databrowse_BrowseRequest>

You can modify the some of the behaviors of this query by changing some of its values in the XML, such as changing the value to dataUnits="KB" to test for file size in kilobytes rather than megabytes. See Supported Parameters Used in these Queries.

Last modified: 12/14/2018 8:49:35 PM