Skip to main content
Hitachi Vantara Knowledge

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. For information on these activities, see Working with search results. You can also save the search criteria as a reusable query. For information on saving search criteria, see Working with saved queries.

NoteWebHelp.png

Note: While the metadata query engine is active, structured searches are called structured queries.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

NoteWebHelp.png

Note: While the metadata query engine is active, the Structured Search page is called the Structured Query page.

StructuredSearchPage.png

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.

Examples of criteria for structured searches are:

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

For a complete list of the properties, operators, and values for structured searches, see Properties for structured searches.

After creating a structured search, you can change it to an advanced search by clicking on Show as advanced. The Advanced Search page opens and shows the specified search criteria translated into the search query language. For more information on advanced searches, see Working with advanced searches.

NoteWebHelp.png

Note: After displaying a structured search as an advanced search, you cannot change it back to a structured search. You can, however, use your browser back button to return to the page showing the structured search.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 HDDS search facility.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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. For descriptions of the properties in the table, see Understanding returned metadata.

Property Operators Values
General

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 on 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)

Security

ACL

does
does not

Exist

Owner

is user
is not user

User currently logged into 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

For information on specifying a value for this property, see Specifying an owner.

Grant

contains
does not contain

One of:

Specified set of permissions

Specified set of permissions and user or group to which those permissions are granted

This property returns objects with ACLs that contain the specified grant.

For information on specifying a value for this property, see Specifying an ACL grant.

Dates

Retention1

is value
is not value

Expired
Not Expired
Deletion Prohibited
Initial Unspecified

is date
is not date
before date
after date

Specified date 2
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 2
Selected date
$now

Change Time

is
is not
before
after

Specified date 2
Selected date
$now

Access Time

is
is not
before
after

Specified date 2
Selected date
$now

Miscellaneous

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 terms3

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 terms3

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 True, the property returns objects that are flagged as replication collisions. If the value is False, the property returns objects that are not flagged as replication collisions.

Content Classes
Content class names4 N/A N/A

1. For information on retention settings, see Retention settings

2. For valid date formats, see Specifying dates. For information on the different metadata time properties, see Understanding returned metadata.

3. Search terms containing Boolean operators in the form of plus and minus signs are not valid in structured queries. For more information on specifying search terms, see Search terms

4. For information on the content class list and its use, see Content classes.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

1_19.jpg

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 Operators 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 date1

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
1. For valid datetime formats, see Specifying dates.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

Using the Find Objects by Owner window

To specify an owner using the Find Objects by Owner window:

1.Click on the select owner control ( FindObject.png ) next to the value field.

2.In the Find Objects by Owner window:

oTo query for objects owned by a specified user:

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 Owner Type section, select User.

In the Owner Name section, type the username of the user account of the object owner.

oTo query for objects that have no owner:

In the Tenant or Domain section, type the name of the tenant that owns the namespace that contains the object.

In the Owner Type section, select Anonymous.

oTo 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, in the Owner Type section, select nobody.

3.Click on Submit. On the Structured Query page, a value appears in the value field for the Owner property.

Typing an owner value

Values for the Owner property for structured queries use the same formats as values for the owner property for advanced queries. For information on these formats, see Properties for advanced queries with the metadata query engine.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

Using the Find Objects by Permissions window

To specify an ACL grant using the Find Objects by Permissions window:

1.Click on the select permissions control ( FindObject.png ) next to the value field.

2.In the Find Objects by Permissions window:

oTo query for objects with ACLs that grant permissions to a specified user:

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 username of the grantee.

oTo query for objects with ACLs that grant permissions to the user account you’re using to access the Console:

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 Grantee Type section, select User.

Leave the Tenant or Domain and Grantee Name fields blank.

oTo query for objects with ACLs that grant permissions to an AD group:

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.

oTo query for objects with ACLs that grant permissions to all users, including those that access the namespace anonymously:

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.

oTo query for objects with ACLs that grant permissions to all authenticated users:

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 Group.

In the Grantee Name section, type authenticated. This value is case sensitive.

3.Click on Submit. On the Structured Query page, a value appears in the value field for the Grant property.

Typing a grant value

Values for the Grant property for structured queries use the same formats as values for the aclGrant property for advanced queries. For information on these formats, see aclGrant property.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Properties for structured searches with the HDDS search facility


The table below presents the properties you can use for structured searches when the HDDS search facility is active. For each property, the table shows the available operators and the values you can select or type. For descriptions of the properties in the table, see Understanding returned metadata.

Property Operators Values
General

Object Type

is
is not
contains
does not contain

Any
Document
Email
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 terms1

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 on a namespace name in the dropdown list.

Each namespace name is followed by the name of the owning tenant in parentheses.

Security

UID2

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.

GID2

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.

Permissions2

is
is not
greater than
less than

Octal number greater than or equal to 0 (zero)3

Dates

Retention4

is value
is not value
is date
is not date
before date
after date

Deletion Prohibited
Expired
Not Expired
Specified date5
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 date5
Selected date
$now

Change Time2

is
is not
before
after

Specified date5
Selected date
$now

Modification Time2

is
is not
before
after

Specified date5
Selected date
$now

Access Time2

is
is not
before
after

Specified date5
Selected date
$now

Miscellaneous

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 documentor unknown

Use unknown for documents for which HCP cannot determine the character set.

Email

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 date5
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
Documents

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

1. Search terms in structured searches cannot include Boolean operators. For more information on specifying search terms, see Search terms

2. This property applies only to objects in the default namespace.

3. For information on octal values for permissions, see Understanding returned metadata.

4. For information on retention settings, see Retention settings.

5. For valid date formats, see Specifying dates. For information on the different metadata time properties, see Understanding returned metadata.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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

To select a date from a calendar:

1.Click on the calendar icon ( CalendarIcon.png ) next to the value field.

2.In the calendar window that appears, either click on the date you want or click on Today. To display the next or previous month, click on the forward or back pointer, respectively, in the area showing the month and year.

The selected date appears in the value field in this format:

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 is the four-digit year, MM is the two-digit month, and DD is the two-digit day.

hh is hours on a 24-hour clock, mm is minutes, and ss is seconds.

Z means 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 on the icon ( NowIcon.png ) 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Performing a structured search


To perform a structured search:

1.In the Search Console, click on the Structured Search tab.

NoteWebHelp.png

Note: When 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.

2.In the Find objects that match field on the Structured Search page:

oSelect any to return objects that satisfy at least one of the criteria you specify.

oSelect all to return objects that satisfy every one of the criteria you specify.

3.Specify the first search criterion:

a.From the property dropdown list, select the property for the criterion.

b.If you selected a content class in step a, select a content property from the content property dropdown list.

c.From the operator dropdown list, select the operator for the criterion.

d.In the value field, either select or type the value for the criterion.

4.For each additional criterion, if any:

a.Click on the add button ( AddButton.png ) to the right of the criterion after which you want to insert the new criterion.

b.Repeat the actions in step 3 above.

5.Click on Search.

To remove a criterion from a structured search, click on the remove button ( RemoveButton.png ) to the right of that criterion. To see the new results, click on Search.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Examples of structured searches


This section shows examples of criteria for structured searches.

Example 1: Search for any of three using the same property

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:

StructuredSearchAnyThree.png

Example 2: Search for all five, including a time span

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:

StructuredSearchAllFive.png

Example 3: Search for held objects in a retention class

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:

StructuredSearchNamespace.png

Example 4: Search for objects with specified text in their custom metadata (metadata query engine only)

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:

StructuredSearchCustomMetadataQueryEngine.png

Example 5: Search for objects with a specified ACL grant (metadata query engine only)

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:

StructuredSearchACLs.png

Example 6: Search using a content property (metadata query engine only)

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.

ContentPropertySearch.png

Example 7: Search for an extracted metadata property (HDDS search facility only)

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:

StructuredSearchExtracted.png

Example 8: Search for expired objects of a particular type (HDDS search facility only)

This example shows an all search for image objects that have expired. On the Structured Search page, the search criteria look like this:

StructuredSearchAllExpiredImage.png

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

 

  • Was this article helpful?