Working with search results
The Search Results page shows the list of objects returned for a query. For each object, this page shows specific metadata.
About search results
The HCP Search Console uses the Search Results page to list the objects that satisfy the criteria you specify for a search. This page has four areas of information:
- The criteria you specified for the query.
- Options for working with the search results.
- Filters for refining the search results.
- The list of returned objects. The objects are numbered for ease of reference.
Partial results.
If this message persists, see your HCP tenant administrator.
Initial search results for individual objects
The information initially returned for each object differs depending on the active search facility. Once you have retrieved the initial information you can ask for additional information for any given object.
Initial results with the metadata query engine
While the metadata query engine is active, the Search Results page initially returns this information for each object in the search results:
- Object directory path and name.
- URL. This is the absolute path to the object. The location is the HCP system, and the root directory is rest for HCP namespaces or fcfs_data for the default namespace.
You can click the URL to access the object.
- Change time.
Here’s an example of the information initially returned for an object while the metadata query engine is active:
The metadata query engine can return a maximum of ten thousand objects in response to a single query. If your query would return more that ten thousand objects, you should run a query with more precise search criteria to ensure that you get all the objects you want.
- Object directory path and name
- URL
- A message indicating that the object has been deleted
Initial results with the Data Discovery Suite search facility
While the Data Discovery Suite search facility is active, the Search Results page initially returns this information for each object in the search results:
- Title (if available) or object name.
- URL. This is the absolute path to the object. The location is the HCP system, and the root directory is rest for HCP namespaces or fcfs_data for the default namespace.
You can click the URL to access the object.
- Size.
- Change time.
Here’s an example of the information initially returned for an object while the Data Discovery Suite search facility is active:
Data Discovery Suite can return a maximum of ten thousand objects in response to a single query. If your search would return more than ten thousand objects, you should run a query with more precise search criteria to ensure that you get all the objects you want.
Viewing returned objects
If you are logged in to the Search Console as a tenant-level user, you can view the content of any object in the search results by clicking the object name or URL. If you are logged in to the Search Console as a system-level user, you do not have permission to view object content. In this case, when you click the object, the Namespace Browser opens and displays the login page. After you log into the Namespace Browser, it displays the object content. If you then return to the Search Console, you need to log in again.
While the Data Discovery Suite search facility is active, you can also view the content of an object by clicking the object title (if available).
Depending on the browser you’re using and the object type, you may be asked whether you want to open the object or save it to disk. When you view the object, it opens in the default application for that object type.
Showing results details
The Search Results page includes a Show details link for each returned object.
When you click this link for an object, the Search Results page shows additional metadata.
To hide additional metadata after displaying it, click Hide details.
Understanding returned metadata
The Search Results page shows metadata for each listed object. You can see some metadata initially. You can view the remaining metadata by showing result details.
The metadata shown varies depending on namespace type and object type. The Search Results page shows as much of this metadata as is available:
Size
The object size, in bytes.
Version ID
The version ID of the object.
Retention
The retention setting for the object, shown as one of these:
- A specific date and time in the future.
- Deletion Prohibited.
- Initial Unspecified.
- A retention class.
- Expired. This includes objects whose retention setting is either a specific date and time in the past or Deletion Allowed.
NoteHCP cannot represent dates later than February 18, 2038, at 22:14:07. Later dates appear as 2/18/2038 22:14:07 (overflow).Hold
An indication of whether the object is on hold. While an object is on hold, it cannot be deleted under any circumstances until it is explicitly released, nor can its retention setting be changed.
While the metadata query engine is active, for an object that’s on hold, the retention setting is followed by | HOLD.
While the Data Discovery Suite search facility is active, this setting is shown as either Held or Not Held.
Custom metadata annotations
(metadata query engine only)
If the object has one or more custom metadata annotations, a list of the annotation names. You can click any annotation name to view the content of that annotation. You can right-click the link to copy the URL for the annotation.
Access control list URL
(metadata query engine only)
If the object has an ACL, the URL for that ACL. You can click this URL to view the content.
The access control list URL consists of the object path followed by a type=acl query parameter. For example, this URL specifies the ACL for an object named Q1_2012.ppt:
https://finance.europe.hcp.example.com/rest/presentations/ Q1_2012.ppt?type=aclIngest time
The date and time the object was created (that is, when the data was added to the namespace).
Access time
The POSIX atime for the object. Users and applications can change this metadata.
While the metadata query engine is active, this metadata is shown for all objects. While the Data Discovery Suite search facility is active, this metadata is shown only for objects in the default namespace.
Modify time
The POSIX mtime for the object. Users and applications can change this metadata.
While the metadata query engine is active, this metadata is shown for all objects. While the Data Discovery Suite search facility is active, this metadata is shown only for objects in the default namespace.
Change time
The POSIX ctime for the object. This is the last time the object metadata changed.
While the metadata query engine is active, this metadata is shown for all objects. While the Data Discovery Suite search facility is active, this metadata is shown only for objects in the default namespace.
Hash value
The cryptographic hash value for the object. The label for this value is the name of the cryptographic hash algorithm used to calculate the value.
DPL
The number of copies of the object data HCP must maintain, as dictated by the service plan that applies to the namespace. DPL stands for data protection level.
Shredding
The shred setting for the object, which indicates whether the object will be shredded when it’s deleted. Shredding is the process of deleting an object and overwriting the place where it was stored in such a way that none of its data or metadata can be reconstructed.
Replication
An indication of whether the object has been replicated to another HCP system.
MIME type
(Data Discovery Suite search facility only)
The MIME type of the object content.
Format
(Data Discovery Suite facility only)
The format of the object content.
Language
(Data Discovery Suite facility only)
The language of the object content.
User ID
The POSIX user ID of the object owner.
While the metadata query engine is active, this metadata is shown for all objects. While the Data Discovery Suite search facility is active, this metadata is shown only for objects in the default namespace.
Group ID
The POSIX ID of the owning group.
While the metadata query engine is active, this metadata is shown for all objects. While the Data Discovery Suite search facility is active, this metadata is shown only for objects in the default namespace.
Permissions
The object permissions in POSIX format and as an octal value.
While the metadata query engine is active, this metadata is shown for all objects. While the Data Discovery Suite search facility is active, this metadata is shown only for objects in the default namespace.
Owner
(metadata query engine only)
For objects in HCP namespaces, the user that owns the object. The owner is an HCP-specific metadata property and does not correspond to the POSIX UID of an object. This value has this format:
USER,location,username
For objects with no owner, this value has this format:
GROUP,location,all_users
In these formats:
location
The location in which the user account of the object owner is defined. For objects with no owner, this is the tenant that owns the namespace that contains the object.
This value can be the name of an HCP tenant or the name of an Active Directory domain preceded by an at sign (@).
username
The user name of the object owner. This value can be the username of a user account that’s defined in HCP or the username of an Active Directory user account. The username for an AD user account can be either the user principal name or the Security Accounts Manager (SAM) account name.
For objects in the default namespace, the value for owner is an empty string.
For objects in HCP namespaces that existed before the HCP system was upgraded from a pre-5.0 release and that have not subsequently had their owner changed, the value for owner is nobody. These objects effectively have no owner.
Author
The author of the object content
Title
The title of the object content
Subject
The subject of the object content
Category
The category of the object content
The text in the email subject field
The message ID
From
The email address of the sender
To
The email addresses of the recipients
Attachments
The names of any files attached to the email
CC
The exposed email addresses of additional recipients
BCC
The hidden email addresses of additional recipients
Send date
The date and time the email was sent
POSIX permissions
POSIX permissions are represented by three 3-character strings — one for the user identified by the POSIX user ID, one for the group identified by the POSIX group ID, and one for all others. From left to write, the positions in each string represent read (r), write (w), and execute (x). Each position has either the character that identifies the applicable permission, meaning the permission is allowed, or a hyphen (-), meaning the permission is denied. Each string is preceded by a hyphen (-).
For example, the string below means that the user identified by the POSIX user ID has all permissions for the object, the group identified by the POSIX group ID has read and execute permissions, and others have only read permission:
-rwxr-xr--
Octal permission values
Permissions are also represented by octal values. Each object has an octal permission value that’s the sum of the octal permission values specified for the object owner, the owning group, and all other users not in that group. The table below shows the value that corresponds to each permission.
| Read | Write | Execute | |
| Owner | 400 | 200 | 100 |
| Group | 040 | 020 | 010 |
| Other | 004 | 002 | 001 |
You can represent permissions numerically by combining these values. For example, the octal value 755 represents these permissions:
POSIX owner has read, write, and execute permissions (700).
POSIX group has read and execute permissions (050).
Other has read and execute permissions (005).
Paging through search results
The Search Results page shows both the number of objects in the search results and the number of pages required to list them, as well as how long the search took, in seconds. The number of pages depends on both the number of objects returned and the number of objects listed on each page.
By default, the Search Console displays ten objects per page. You can use the results/page option on the Search Results page to select a different number. The choices are 10, 20, 50, 75, 100, and 200.
When you select a number of objects, the Search Results page immediately changes the number of objects it lists on each page.
To page through the search results, you can take either of these actions:
- To go forward or backward one page at a time, click the next or back arrow on either side of the page number information.
- To go to a specific page, in the go to page field, type the number of the page you want and click Go..
Sorting search results
The default order in which the Search Results page lists returned objects differs depending on the active search facility:
- While the metadata query engine is active, returned objects are listed in the order of the number of search criteria the object matches. Objects that match the same number of criteria are not listed in any specific order.
- While the Data Discovery Suite search facility is active, returned objects are listed in order by their relevance to the search. Relevance is determined by factors such as the creation date of the object and the distance between occurrences of search terms in the object.
You can change the order in which returned objects are listed on the Search Results page by selecting a different sort order:
- While the metadata query engine is active, you can sort in ascending or descending order by:
- Object size
- Change time
- Ingest time
- Retention setting
- While the Data Discovery Suite search facility is active, you can sort in ascending or descending order by:
- Object size
- Ingest time
- Retention setting
- For email only, the time the email was sent
To change the sort order on the Search Results page, select the order you want in the Sort results field.
When you select a sort option, the Search Results page immediately reorders the list of objects.
Showing or hiding the query
When you perform a search, the criteria you used to form the query remain displayed on the Search Results page. You can hide or redisplay these criteria at any time:
- To hide the query criteria, click Hide Query in the upper right portion of the page.
- To redisplay the query after hiding it, click Show Query.
Filtering search results
The Search Results page includes several types of filters that you can use to refine the results of a search:
- Document format; that is, the format of the object content (Data Discovery Suite search facility only)
- Retention setting (metadata query engine only)
- Retention class (metadata query engine only)
- Hold status (metadata query engine only)
- Namespace
Search results page
When you select a filter, the Search Results page immediately redisplays the search results with only the objects that match that filter.
You can apply multiple filters to the same list of objects to remove the objects that aren’t of interest. For example if your results included objects in a namespace named finance, you could first refine the list by filtering for objects in the finance namespace, thereby excluding objects in all other namespaces. Then you could further refine the same list by filtering for objects currently on hold, thereby excluding objects that are not on hold. The resulting list would include only objects in the finance namespace that are on hold.
The Search Results page shows each filter currently in effect as a checkbox option in the Active result filters area below the search criteria.
To remove a filter, deselect it in the Active result filters area. Again, the Search Results page immediately redisplays the search results, this time including the objects previously removed by that filter.
When you apply filters, they remain in effect until you clear the search results either by moving to a different page or, for structured searches only, by clicking Clear. If you change the query criteria without first clearing the current search results, any filters currently in effect are applied to the results of the new search.
Filtering by document format
While the Data Discovery Suite facility is active, the Search Results page lists the document formats of the objects in the search results, along with the number of returned objects in each format. The document format of an object is the format of its data content before that data was added to the namespace. Examples of document formats are PDF, JPEG, and XML.
The document formats on the Search Results page are listed in descending order of frequency. You can select only one document format to use as a filter in any given search.
When you select a document format, the Search Results page redisplays the search results, including only objects whose content is in the selected format. The name of the format appears in the Active result filters area.
Objects with an unrecognized format are listed as Unknown format. Objects whose content is larger than ten MB or whose compressed content expands to more than ten MB are also listed this way. Additionally, plain text objects that use EBCDIC encoding are listed this way.
Filtering by retention setting
While the metadata query engine is active, the Search Results page lists the possible object retention settings, along with the number of returned objects with each setting. The possible retention settings are Initial Unspecified, Deletion Prohibited, Expired, and Not Expired. Expired means the retention setting is either a specific date and time in the past or Deletion Allowed. Not Expired means the retention setting is a specific date and time in the future.
When an object is assigned to a retention class, HCP indexes it by that class but does not remove the preexisting retention setting from the index. Therefore, if an object is assigned to a retention class after it was stored, it is still included in the count for the retention setting that it initially had.
You can select only one retention setting to use as a filter in any given search.
When you select a retention setting, the Search Results page redisplays the search results, including only objects with the selected setting. The setting itself appears in the Active result filters area.
Filtering by retention class
While the metadata query engine is active, the Search Results page lists retention classes to which objects in the search results belong, along with the number of returned objects in each class. The list includes only the one hundred classes that occur most often in the search results.
The retention classes on the Search Results page are listed in descending order of frequency. You can select only one retention class to use as a filter in any given search.
When you select a retention class, the Search Results page redisplays the search results, including only objects in the selected class. The name of the retention class appears in the Active result filters area.
Filtering by hold status
While the metadata query engine is active, the Search Results page lists the possible hold statuses, Held or Not Held, along with the number of returned objects to which each setting applies.
When you select Held or Not Held, the Search Results page redisplays the search results, including only objects with the selected hold status. The setting itself appears in the Active result filters area.
Filtering by namespace
The Search Results page lists namespaces in which objects in the search results are located, along with the number of returned objects in each namespace. The name of the tenant that owns the namespace follows the namespace name, in parentheses. The list includes only the 15 namespaces that appear most often in the search results.
The namespaces on the Search Results page are listed in descending order of frequency. You can select only one namespace to use as a filter in any given search.
When you select a namespace, the Search Results page redisplays the search results, including only objects in the selected namespace. The name of the namespace appears in the Active result filters area.
Performing operations on returned objects
The Search Console allows you to perform operations on multiple objects at a time. You can use the Console to:
- Hold objects or release objects that are on hold.
- Delete or purge objects. Purge applies only to HCP namespaces, which can store multiple versions of objects. Purging an object deletes all versions of that object, including the current version. Deleting an object with multiple versions deletes only the current version.NoteHCP can delete or purge up to 2,000 objects in a single operation. If the search results include more than that, only the first 2,000 are deleted or purged. For all other operations, the operation works on the entire set of search results.
- Perform privileged delete or privileged purge operations. These operations work on objects that are under retention as well as on those that are not. When you perform a privileged operation, you’re required to specify a reason for it.
- While the metadata query engine is active, change object owners to an HCP user, an Active Directory user, or no owner. This operation applies only to objects in HCP namespaces.
- While the metadata query engine is active, set ACLs on objects. With this operation, the ACL you specify is added to any object without an ACL and replaces any existing ACLs on objects with ACLs. This operation applies only to objects in HCP namespaces.
- While the metadata query engine is active, update ACLs on objects. With this operation:
- For objects without ACLs, the ACL you specify is set for those objects.
- For objects with ACLs, the existing ACLs are updated with the grants in the ACL you specify.
If an existing ACL doesn’t have a grant for a user or group that you specify, a grant for that user or group is added to the existing ACL. If an existing ACL already has a grant for a user or group that you specify, the grant in the existing ACL is replaced with the grant you specify for that user or group.
This operation applies only to objects in HCP namespaces.
For any of the operations mentioned above to work on the objects in any given namespace:
- The namespace must be configured to allow the operation.
- You must have permission to perform the operation.
A requested operation works only on the objects in namespaces that support the operation and for which you have permission to perform the operation. Other objects in the search results are not affected.
You select the operation you want to perform from the Control operations field. In some cases, this field may show operations that are not allowed for some or all of the listed objects. If you try to perform an invalid operation on an object, the operation fails for that object.
Performing actions on returned objects causes the metadata query engine to update its index. However, even though these actions happen immediately, they may not be reflected in search results until the index update is complete.
While the Data Discovery Suite search facility is active, changes caused by performing these operations are reflected in the next update of the index.
Placing all the objects in the current search results on hold
Procedure
On the Search Results page, in the Control operations field, select Place results on hold.
In the window that opens, click Continue.
Results
Releasing all held objects in the current search results
Procedure
On the Search Results page, in the Control operations field, select Release hold on results.
In the window that opens, click Continue.
Results
Deleting all objects in the current search results except those that are under retention or on hold
Procedure
On the Search Results page, in the Control operations field, select Delete results.
In the window that opens, click Continue.
Results
Deleting all objects in the current search results, including those that are under retention but excluding those that are on hold
Procedure
On the Search Results page, in the Control operations field, select Privileged Delete results.
In the field in the window that opens, type a reason for the delete operation.
The reason text must be from one through 1,024 characters long and can contain any UTF-8 characters, including white space.Click Continue.
Results
Purging all versions of all the objects in the current search results except those that are under retention or on hold
Procedure
On the Search Results page, in the Control operations field, select Purge results.
In the window that opens, click Continue.
Results
Purging all versions of all the objects in the current search results, including those that are under retention but excluding those that are on hold
Procedure
On the Search Results page, in the Control operations field, select Privileged Purge results.
In the field in the window that opens, type a reason for the purge operation.
The reason text must be from one through 1,024 characters long and can contain any UTF-8 characters, including white space.Click Continue.
Results
Changing the ownership of all objects in the current search results
Procedure
On the Search Results page, in the Control operations field, select Change owner of results.
In the window that opens:
- To specify an HCP user account, type the user name of the account in the Username field. Leave the Domain field blank.
- To specify an Active Directory user, type the user name of an AD user account in the Username field and the domain in which the account is defined in the Domain field. The user name can be either the user principal name or the Security Accounts Manager (SAM) account name for the AD user account.
- To specify that the objects have no owner, leave both the Username and Domain fields blank.
Click Continue.
Results
Setting an ACL on each object in the current search results
Procedure
On the Search Results page, in the Control operations field, select Set ACL on results.
In the field in the window that opens, type the ACL XML.
This XML can be at most 8,192 characters long.Click Continue.
Results
Updating the existing ACLs for all objects in the current search results
Procedure
On the Search Results page, in the Control operations field, select Update ACL on results.
In the field in the window that opens, type the ACL XML.
This XML can be at most 8,192 characters long.Click Continue.
Results
Access control lists
An access control list grants permissions for individual objects to specified users or groups of users. ACLs are specified in XML format.
An ACL contains up to one thousand access control entries (ACEs). Each ACE specifies one user or one group of users and the permissions granted to that user or group. In the ACL body, an ACE is represented by the grant element.
The permissions you grant to users and groups in an ACL must be equal to or less than your permissions for the object. You cannot use an ACL to grant a permission that you don’t already have.
ACL permissions
The following list lists the permissions you can grant through an ACL along with the operations they let you perform.
Read
- Retrieve objects and system metadata
- Check for and retrieve custom metadata
Read_ACL
Check for and retrieve ACLs
Write
- Add objects
- Create directories
- Set and change system and custom metadata
Write_ACL
Set and change ACLs
Delete
Delete objects, empty directories, custom metadata, and ACLs
XML format
The body of an ACL has the XML elements shown below. The elements at each hierarchical level can occur in any order.
<?xml version="1.0" ?>
<accessControlList>
<grant>
<grantee>
<type>(user|group)</type>
<name>(hcp-username|
active-directory-username|
active-directory-group-name|
all_users|
authenticated)
</name>
If the name element specifies an Active Directory
user or
group, include the domain entry
<domain>active-directory-domain</domain>
</grantee>
<permissions>
Any combination of the following
<permission>READ</permission>
<permission>READ_ACL</permission>
<permission>WRITE</permission>
<permission>WRITE_ACL</permission>
<permission>DELETE</permission>
</permissions>
</grant>
Up to 999 additional grant elements
</accessControlList>
Here is an example of an ACL that grants read and write permission to all users and grants read, write, and delete permission to the tenant-level HCP user with the username lgreen:
<?xml version="1.0" ?>
<accessControlList>
<grant>
<grantee>
<name>all_users</name>
<type>group</type>
</grantee>
<permissions>
<permission>READ</permission>
<permission>WRITE</permission>
</permissions>
</grant>
<grant>
<grantee>
<name>lgreen</name>
<type>user</type>
</grantee>
<permissions>
<permission>READ</permission>
<permission>WRITE</permission>
<permission>DELETE</permission>
</permissions>
</grant>
</accessControlList>
The XML for an ACL has a single top-level accessControlList element. All ACLs must contain this element. The XML for an ACL also contains the elements listed in the table below.
| Element | Values | Description |
| grant | N/A |
Container for the An ACL can contain up to one thousand |
| grantee | N/A | Child of the grant element. Container for the name, type, and domain elements. |
| name |
One of:
|
Specifies the user or group of users to which the ACL grants permissions. HCP has two special groups that you can specify in an ACL:
To grant permissions to one of these special groups, specify The Search Console returns an error if a given user or group is specified in more than one |
| type |
One of:
|
Specifies the type of the value specified in the The Search Console returns an error if the value of the |
| domain | The name of an Active Directory domain |
Specifies the Active Directory domain that contains the user account or group specified in the This element is required if the |
| permissions | N/A | Container for any combination of permission entries. |
| permission |
One of:
| Child of permissions entry. Specifies a permission granted to the user or group specified in the name entry. |
Exporting search results
You can export the results of a search as a comma-separated-values (CSV) or XML file for use with other applications. For example, you could use a CSV or XML file containing exported search results to generate a list of selected objects for a regulatory body. Or, you could use an export file as input to an application that analyzes namespace content.
For each object in the search results, an export file contains either the object URL alone (metadata query engine only) or the URL along with a specific subset of the object metadata. The file does not contain the object content. However, you can use the object URL to retrieve the object content in a separate operation.
When the export file includes object metadata, the values for each object in the file are, in order:
- Object URL
- Object size, in bytes
- Content format (always blank when the metadata query engine is active)
- Cryptographic hash algorithm used to calculate the cryptographic hash value of the object
- Cryptographic hash value of the objectNoteIf HCP has not yet calculated the cryptographic hash value for an object, the value in the export file is an empty string.
The same metadata is exported for each object, regardless of whether its details are showing on the Search Results page and regardless of which search facility is active.
To export the current search results, select the format you want in the Export results field. The available formats are:
- While the metadata query engine is active:
- To export only the object URLs:
- XML format (short)
- CSV format (short)
- To export both the object URLs and the object metadata:
- XML format (detailed)
- CSV format (detailed)
NoteExporting only object URLs is significantly faster than exporting both the URLs and the object metadata. Additionally, when exporting both the URLS and metadata for a large number of objects, the resulting export file may not contain all the expected objects. - To export only the object URLs:
- While the Data Discovery Suite search facility is active:
- XML format
- CSV format
Depending on the browser you’re using and the file type you’ve selected, you may be asked whether you want to open or save the export file.
Export files are named results.selected-type, where selected-type is either CSV or XML. To prevent a subsequent export operation from overwriting an exported file, you should give the file a new name that identifies its contents (for example, held_objects_06082012.xml).