Working with structured searches
Structured searches are one of the three types of searches you can perform from the HCP Search Console. A structured search can be based on metadata values as well as on text matching. You can specify multiple criteria for structured searches and indicate whether objects need to satisfy any or all of them.
This chapter provides instructions for performing structured searches. It explains the rules for specifying the search criteria and the options that determine whether objects are included in the search results. It also includes several examples.
Once you have the results of a structured search, you can filter and export them.
About structured searches
Structured searches work by comparing criteria you specify to various properties of objects. These criteria can be based on object metadata as well as on object content. You can also specify whether objects need to meet any or all of the specified criteria.
To perform a structured search, you use the Structured Search page of the Search Console.
Within a single structured search, you can specify multiple criteria. With the exception of the content class property (metadata query engine only), each criterion has the form:
propertyoperatorvalue
On the Structured Search page, you select both properties and operators from dropdown lists. Depending on the property, you either select or type the value.
Object Size less than 2049 Namespace is finance (europe) Title contains budget proposal Shredding is not Shred on Delete Ingest Time before 2011-11-30T14:55:55-0500
After creating a structured search, you can change it to an advanced search by clicking Show as advanced. The Advanced Search page opens and shows the specified search criteria translated into the search query language.
Properties for structured searches
The properties available for structured searches depend on the active search facility. The tables in the following sections present the properties you can use for structured queries with the metadata query engine and structured searches with the Data Discovery Suite search facility.
Properties for structured queries with the metadata query engine
The table below shows the properties you can use for structured queries when the metadata query engine is active. For each property, the table shows the available operators and the values you can select or type.
| Property | Operators | Values |
| Namespace |
is is not |
Name of a namespace searchable by the user To specify a value for this property, type the name of a namespace in the value field and then click a namespace name in the dropdown list. Each namespace name is followed by the name of the owning tenant in parentheses. |
| Object Name |
contains does not contain contains phrase does not contain phrase | Part or all of an object path or name, not including rest or data (HCP namespaces) or fcfs_data (default namespace) |
| Property | Operators | Values |
| ACL |
does does not | Exist |
| Owner |
is user is not user |
User currently logged in to the Metadata Query Engine Console These operators do not appear if the user is logged in using a system-level user account. |
|
is is not |
Specified user | |
| Grant |
contains does not contain |
One of:
This property returns objects with ACLs that contain the specified grant. |
| Property | Operators | Values |
| Retention |
is value is not value |
Expired Not Expired Deletion Prohibited Initial Unspecified |
|
is date is not date before date after date | Specified date | |
| Retention Class |
is is not |
Selected retention class No Retention Class |
|
contains does not contain | Part or all of a retention class name | |
| Ingest Time |
is is not before after |
Specified date Selected date $now |
| Change Time |
is is not before after |
Specified date Selected date $now |
| Access Time |
is is not before after |
Specified date Selected date $now |
| Property | Operators | Values |
| Size |
is is not greater than less than |
Object size, in bytes This is the exact size of the object content. For example, to search for a two KB object, you need to specify 2048, not 2000. |
| Retention Hold |
is is not | Held |
| Shredding |
is is not | Shred on Delete |
| Hash |
is is not | Cryptographic hash algorithm followed by a space and the cryptographic hash value for an object |
| Custom Metadata |
does does not | Exist |
| Custom Metadata Annotation |
is is not |
One or more search terms* If full text of custom metadata is indexed, this property returns the annotations associated with the matching custom metadata. |
| Custom Metadata Content |
contains does not contain contains phrase does not contain phrase |
One or more search terms* If full text of custom metadata is indexed, this property returns the objects associated with the matching custom metadata. |
| Replication Collision |
is is not |
True False If the value of this property is |
| * Search terms containing Boolean operators in the form of plus and minus signs are not valid in structured queries. | ||
| Property | Operators | Values |
| Content class names | N/A | N/A |
Content classes
The Content Classes section displays a list of the content classes defined for the tenant. When you select a content class, an additional field appears in the query area, as shown below.
The dropdown list for the added field contains the content properties in the selected content class.
Each content property has a data type, such as integer or string, that determines the operators and values you can specify. The table below lists the possible data types.
| Data type | Operator | Values |
| Boolean |
is is not |
True (matches 1 or strings starting with T or t) False (matches all other values) |
|
does does not | exist | |
| Datetime |
is is not before after | Specified date |
|
does does not | exist | |
| Float |
is is not greater than less than greater than or equals less than or equals |
Floating point number. Floating point numbers can include a positive or negative sign, digits, a decimal point, and an exponent that starts with E. Here are some sample floating point numbers: 1328.978 -3746.12 954.33E5 |
|
does does not | exist | |
| Integer |
is is not greater than less than greater than or equals less than or equals | Positive or negative integer |
|
does does not | exist | |
| String |
is is not | Text string |
|
does does not | exist | |
| Tokenized |
contains does not contain contains phrase does not contain phrase | One or more search terms |
|
does does not | exist |
The does and does not operators test for the existence of the specified content property. That is, does exist condition matches only objects with custom metadata that have the specified content property. One use for the does exist condition is to limit the scope of the is not and does not contain operators.
The is not and does not contain operators match all objects that don't have the content property value specified by the value field. As a result, the criterion matches objects without the content property, and even those with no custom metadata at all. To make sure that a query matches only objects with custom metadata identified by the content property, use two criteria for the content property, one with an is not or does not contain operator and one with a does operator with the exist value.
Specifying an owner
With the Owner property, you can specify an owner using the Find Objects by Owner window or you can type a value. You can specify an owner only when the operator is is or is not.
Procedure
Click the select owner control (
) next to the value field.In the Find Objects by Owner window, in the Tenant or Domain section, type the name of the tenant or AD domain in which the user account of the object owner is defined
If you type an AD domain, precede it with an at sign (@).In the in the Owner Name section:
- To query for objects owned by a specified user, type the user name of the user account of the object owner. Values for the
Ownerproperty for structured queries use the same formats as values for the owner property for advanced queries. - To query for objects that have no owner, select Anonymous
- To query for objects that existed before the HCP system was upgraded from a pre-5.0 release and that have not subsequently had their owner changed, select nobody.
- To query for objects owned by a specified user, type the user name of the user account of the object owner. Values for the
Click Submit.
Results
Specifying an ACL grant
With the Grant property, you can specify an ACL grant using the Find Objects by Permissions window or you can type a value.
Values for the Grant property for structured queries use the same formats as values for the aclGrant property for advanced queries.
Query for objects with ACLs that grant permissions to a specified user
Click the select permissions control (
) next to the value field.In the Grantee has these permissions section, select any combination of Read, Write, Delete, Read ACL, and Write ACL.
ACLs on returned objects can grant more permissions than the ones you select. If you do not select any permissions, ACLs on returned objects grant any combination of permissions.In the Tenant or Domain section, type the name of the HCP tenant or AD domain in which the user account of the grantee is defined.
If you type an AD domain, precede it with an at sign (@).In the Grantee Type section, select User.
In the Grantee Name section, type the user name of the grantee.
Click Submit.
On the Structured Query page, a value appears in the value field for the Grant property.
Query for objects with ACLs that grant permissions to the user account you’re using to access the Console
Click the select permissions control (
) next to the value field.In the Grantee has these permissions section, select any combination of Read, Write, Delete, Read ACL, and Write ACL.
ACLs on returned objects can grant more permissions than the ones you select. If you do not select any permissions, ACLs on returned objects grant any combination of permissions.In the Tenant or Domain section, leave the field blank.
In the Grantee Type section, select User.
In the Grantee Name section, leave the field blank.
Click Submit.
On the Structured Query page, a value appears in the value field for the Grant property.
Query for objects with ACLs that grant permissions to an AD group
Click the select permissions control (
) next to the value field.In the Grantee has these permissions section, select any combination of Read, Write, Delete, Read ACL, and Write ACL.
ACLs on returned objects can grant more permissions than the ones you select. If you do not select any permissions, ACLs on returned objects grant any combination of permissions.In the Tenant or Domain section, type the name of the AD domain in which the group is defined, preceded by an at sign (@).
In the Grantee Type section, select Group.
In the Grantee Name section, type the name of the AD group.
Click Submit.
On the Structured Query page, a value appears in the value field for the Grant property.
Query for objects with ACLs that grant permissions to all users, including those that access the namespace anonymously
Click the select permissions control (
) next to the value field.In the Grantee has these permissions section, select any combination of Read, Write, Delete, Read ACL, and Write ACL.
ACLs on returned objects can grant more permissions than the ones you select. If you do not select any permissions, ACLs on returned objects grant any combination of permissions.In the Tenant or Domain section, type the name of an HCP tenant.
In the Grantee Type section, select Anonymous.
Click Submit.
On the Structured Query page, a value appears in the value field for the Grant property.
Query for objects with ACLs that grant permissions to all authenticated users
Click the select permissions control (
) next to the value field.In the Grantee has these permissions section, select any combination of Read, Write, Delete, Read ACL, and Write ACL.
ACLs on returned objects can grant more permissions than the ones you select. If you do not select any permissions, ACLs on returned objects grant any combination of permissions.In the Tenant or Domain section, type the name of the HCP tenant.
In the Grantee Type section, select Group.
In the Grantee Name section, type authenticated.
This value is case sensitive.Click Submit.
On the Structured Query page, a value appears in the value field for the Grant property.
Properties for structured searches with the Data Discovery Suite search facility
The tables below present the properties you can use for structured searches when the Data Discovery Suite search facility is active. For each property, the table shows the available operators and the values you can select or type.
| Property | Operators | Values |
| Object Type |
is is not contains does not contain |
Any Document Image Multimedia XML Unknown |
| Object Content |
contains all of contains any of contains exactly does not contain all of does not contain any of does not contain exactly |
One or more search terms* This property is the equivalent of a simple search. |
| Object Path |
contains does not contain | Part or all of an object path or name, not including rest or data (HCP namespaces) or fcfs_data (default namespace) |
| Object Format |
contains does not contain | File name extension of a recognized document format |
| Namespace |
is is not |
Name of a namespace searchable by the user To specify a value for this property, type the name of a namespace in the value field and then click a namespace name in the dropdown list. Each namespace name is followed by the name of the owning tenant in parentheses. |
| * Search terms in structured searches cannot include Boolean operators. | ||
| Property | Operators | Values |
| UID1 |
is is not greater than less than |
Integer greater than or equal to 0 (zero) This is the POSIX user ID of the object owner. |
| GID1 |
is is not greater than less than |
Integer greater than or equal to 0 (zero) This is the POSIX ID of the owning group for the object. |
| Permissions1 |
is is not greater than less than | Octal number greater than or equal to 0 (zero) |
| * This property applies only to objects in the default namespace. | ||
| Property | Operators | Values |
| Retention |
is value is not value is date is not date before date after date |
Deletion Prohibited Expired Not Expired Specified date Selected date |
| Retention Class |
is is not contains does not contain | Part or all of a retention class name |
| Ingest Time |
is is not before after |
Specified date Selected date $now |
| Change Time* |
is is not before after |
Specified date Selected date $now |
| Modification Time* |
is is not before after |
Specified date Selected date $now |
| Access Time* |
is is not before after |
Specified date Selected date $now |
| * This property applies only to objects in the default namespace. | ||
| Property | Operators | Values |
| Size |
is is not greater than less than |
Object size, in bytes This is the exact size of the object content. For example, to search for a two KB object, you need to specify 2048, not 2000. |
| Retention Hold |
is is not | Held |
| Shredding |
is is not | Shred on Delete |
| Hash |
is is not | Cryptographic hash value for an object |
| Language |
is is not | Selected language |
| Character Set |
contains does not contain |
Part or all of the name of the character set or encoding used in the document or Use |
| Property | Operators | Values |
| Email To |
contains does not contain | Part or all of an email recipient name |
| Email From |
contains does not contain | Part or all of an email sender name |
| Email CC |
contains does not contain | Part or all of an email cc name |
| Email BCC |
contains does not contain | Part or all of an email bcc name |
| Email Subject |
contains does not contain | Part or all of an email subject |
| Email Sent Date |
is is not before after |
Specified date Selected date $now |
| Email Message ID |
contains does not contain | Part or all of an email message ID |
| Email Attachment Name |
contains does not contain | Part or all of the name of a file attached to an email |
| Property | Operators | Values |
| Author |
contains does not contain | Part or all of a document author’s name |
| Subject |
contains does not contain | Part or all of a document subject |
| Title |
contains does not contain | Part or all of a document title |
| Category |
contains does not contain | Part or all of a document category name |
Specifying dates
When a metadata property requires a date value, you can either select the date from a calendar, select the current date and time, or type a value. The first two options appear when you select the metadata property.
Selecting a calendar date
Procedure
Click the calendar icon (
) next to the value field.In the calendar window that appears, either click the date you want or click Today.
To display the next or previous month, click the forward or back pointer, respectively, in the area showing the month and year.
Results
YYYY-MM-DD
In this format, YYYY is the four-digit year, MM is the two-digit month, and DD is the two-digit day. For example, if you select the day shown on the calendar above, the value field shows:
2011-11-05
Typing a date
You can use these three formats to specify the date and, optionally, time for a metadata property:
YYYY-MM-DD YYYY-MM-DDThh:mm:ss YYYY-MM-DDThh:mm:ssZ
In these formats:
YYYY
the four-digit year
MM
the two-digit month
DD
the two-digit day
hh
hours on a 24-hour clock
mm
minutes
ss
seconds
Z
the time is in UTC.
The first two of these formats are assumed to be in the same time zone as the HCP time setting. The third one is in UTC.
Here’s an example of a date and time in the second format shown above:
2011-11-04T14:00:00
Selecting the current date and time
To select the current date and time, click the icon (
) to the right of the calendar icon. The value field shows:
$now
Each time you run a saved query that uses the $now variable, the variable is replaced by the current date and time.
Performing a structured search
Procedure
In the Search Console, click the Structured Search tab.
NoteWhen the metadata query engine is active, the Structured Search tab is called the Structured Query tab and the Search button is called the Query button.In the Find objects that match field on the Structured Search page:
- To return objects that satisfy at least one of the criteria you specify, select any.
- To return objects that satisfy every one of the criteria you specify, select all.
Specify the first search criterion:
From the property dropdown list, select the property for the criterion.
If you selected a content class in step a, select a content property from the content property dropdown list.
From the operator menu, select the operator for the criterion.
In the value field, either select or type the value for the criterion.
For each additional criterion, if any:
Click the add button (
) to the right of the criterion after which you want to insert the new criterion.Repeat the actions in step 3 above.
Click Search.
Next steps
) to the right of that criterion. To see the new results, click Search.Examples of structured searches
This example shows an any search for objects with a retention class of HlthReg-107, HlthReg-225, or HlthReg-312. On the Structured Search page, the search criteria look like this:
This example shows an all search for objects in a namespace named Finance that expire between December 31, 2014 and January 1, 2016, are not on hold, and will be shredded on delete. On the Structured Search page, the search criteria look like this:
This example shows an all search for objects in the finance namespace owned by the europe tenant that belong to the SEC-17a retention class and are on hold. On the Structured Search page, the search criteria look like this:
This example shows an all search for objects that have custom metadata that contains x-ray. On the Structured Search page, the search criterion looks like this:
This example shows an all search for objects with ACLs that grant delete permission to the user pdgrey, whose user account is defined in the europe tenant. On the Structured Search page, the search criterion looks like this:
This example shows a query using the Sales content property of the Regions content class. The Sales content property has the Float data type. The query will find any object with custom metadata that identifies the region as having aggregate sales of at least $3,000,000.00. To search for a floating point number, you need to type only the numeric value, without a dollar sign or commas. Because the query is for a whole dollar figure, the decimal value is optional and has been omitted.
This example shows an all search for objects that have an extracted metadata property named Security set to classified and contain either environmental impact or impact statement. On the Structured Search page, the search criteria look like this:
This example shows an all search for image objects that have expired. On the Structured Search page, the search criteria look like this:
