Digital Marketing: Leveraging the HP MediaBin APIs: Part 3 – Searching

This is the third post in a blog series on HP MediaBin APIs.

 

In this post, we’ll explore one of the most commonly used set of API calls in MediaBin – the Search API.  This API is used frequently and—as we will see—can be quite flexible.  MediaBin returns search results in the form of a temporary collection.  The advantage to this strategy is that any code written to process the contents of a collection will also work with search results.  This temporary collection is lightweight and will eventually be lost when you log off, unless you take steps to persist it. 

 

The simplest search is performed using the MBCollection_AssetSearch API call.  It takes just one parameter, a string, and corresponds to the sort of search you might do in the MediaBin Client application using the “Search for assets…” free-text search box:

 

MB1.png

 

The result is a (temporary) collection, which you can page through using the Pager calls.

 

This works well if you’re looking for assets exactly matching a search query you might enter in the free-text search box.  In a later blog post, we’ll show some specialized techniques you can use to do some sophisticated searching with this basic call.  For the majority of advanced searches though, you’ll want to use MBCollection_AdvancedAssetSearchEx, which provides all the flexibility you see in the MediaBin Client’s “Advanced Search” page.  This API allows you to search over specific metadata values, combined with logical AND/OR operators to construct quite specific search queries.  In order to accommodate the widest variety of queries, the Advanced Search API is very sophisticated.  As a result, the process of building an appropriate query will take a bit of explanation. 

 

To start, let’s introduce some of the basics.  The basic element of a search is a MBAdvancedSearchConstraint object, which represents a single search term.  These can be combined in simple or complex ways to generate the search query eventually sent to MBCollection_AdvancedAssetSearchEx.

 

The first thing you might notice about the MBAdvancedSearchConstraint is that it requires the MetadataID for the metadata field that you want to search over.  There are a few ways to obtain this information.  For simple applications, you can export the Metadata definition for the item over which you’ll be running the search.  The GUID for the item will be in the exported metadata XML file.  For system (built-in) metadata, please refer to the table in Appendix A of the “Virage MediaBin Programming Reference Guide” titled “Searchable MediaBin Metadata GUIDs”. 

 

A more robust way to determine this GUID is through the MediaBin Metadata Catalog.  Retrieving the catalog from the MediaBin Server will give you a way to look up the GUID of any metadata item at runtime.  This can be helpful when you have multiple MediaBin Server instances (e.g. a Development and a Production system) which will typically have different GUIDs for the same metadata field.

 

To get the Metadata Catalog, create a Metadata pager via:

 

MDPager = ws.mbPagerCacheCreateMetadataDefinitionPager("", ""); 

 

You may then use this pager to enumerate the metadata GUIDs in the catalog, storing them in a convenient object for later use.  In Java, I typically use a Hashtable to make it simple to look up a metadata’s GUID from its name.

 

An Advanced Search is built of two principal objects: the MBAdvancedSearchConstraint and the MBAdvancedSearchConstraintGroup.

  • MBAdvancedSearchConstraint - The basic unit of a search in MediaBin.  This object represents one term in what can be a very complex search. 
  • MBAdvancedSearchConstraintGroup - Multiple MBAdvancedSearchConstraint may be combined into a MBAdvancedSearchConstraintGroup based on a common logical operator.  Every search must have at least one MBAdvancedSearchConstraint, however, you may have multiple constraint groups to represent the exact combination of search predicates you need.  This allows you to express any arbitrary search as a combination of terms and logical operators.  It will be simplest if you first express your search in normal form (either conjunctive or disjunctive).  In any event, the API expects the clauses in your search term to be organized by common logical operator, so the fewer of these terms you need to manage, the better. 

To build the search itself, first create a MBAdvancedSearchConstraint for each of the search constraints you will need.  The MBAdvancedSearchConstraint has three components: MetadataID, SeachOperator and MetadataValue.

  • MetadataID – the GUID of the metadata field to be searched over
  • SearchOperator- the operator for the search.  Since these can be a little hard to decipher, here’s a table breaking them out based on the type of metadata involved:

Metadata Type

Operators

String

Equality, Inequality, Contains, NotContains, StartsWith, NotStartsWith, OpExists, OpAbsent

StringList

Equality, Inequality, OpExists, OpAbsent

Date

LessThan, GreaterThan, Equality, Inequality, OpExists, OpAbsent

DateTime

LessThan, GreaterThan, Equality, Inequality, OpExists, OpAbsent

Array of String

Contains, OpExists, OpAbsent

Array of Int

Equality, Inequality, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, OpExists, OpAbsent

Array of Float

Equality, Inequality, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, OpExists, OpAbsent

Year

LessThan, GreaterThan, Equality, Inequality, OpExists, OpAbsent

ValueList

Equality, Inequality, OpExists, OpAbsent

Boolean

Equality, Inequality, OpExists, OpAbsent

 

For array types, the search runs over each element in the array, and the operator is applied to each element in turn.  The search is successful if any element in the array matches the search criteria

  • MetadataValue– The value against which the search will run (leave unset for existence searches)

Here’s an example of a single search constraint – in this case we’re checking for all assets which have a value set for the “keywords” metadata.  Note the use of a hash to look up the GUID for the “Keywords” metadata item:

 

// create constraint
MBAdvancedSearchConstraint searchConstraint = new MBAdvancedSearchConstraint()  ;
searchConstraint.setMetadataID(mdCatalog.get("Keywords")) ;
searchConstraint.setSearchOperator("OpExists") ;
searchConstraint.setMetadataValue((Object) null);
// add it to our list
constraintList.add(searchConstraint) ;

 

Now that we know how to build individual search constraints, we will assemble a MBAdvancedSearchConstraintGroup for each clause in our search which uses the same logical operator.  To do this, create a MBAdvancedSearchConstraintGroup and add the appropriate search constraints to it:

 

// AND the constraintList together by adding them to a constraint group
MBAdvancedSearchConstraintGroup constraintGroup = new MBAdvancedSearchConstraintGroup();
constraintGroup.setBooleanOperator("AND") ;
// package up the constraintList
ArrayOfAnyType constraintArray = new ArrayOfAnyType() ;
constraintArray.getAnyType().addAll(constraintList);
constraintGroup.setItems(constraintArray) ;
// and save this Group in the list we're creating
constraintGroupList.add(constraintGroup) ;

 

If we have an additional set of terms (e.g. terms we’d like to “OR” together), we simply create another MBAdvancedSearchConstraintGroup just like we did above and add it to the list we’re creating in constraintGroupList. 

 

Finally, we combine all the Constraint Groups together into yet another ConstraintGroup which is passed to the search API.  Note here we also can set a logical operator:

 

// OR the results of the previous two groups
constraintGroup = new MBAdvancedSearchConstraintGroup();
constraintGroup.setBooleanOperator("OR") ;
constraintGroupArray.getAnyType().addAll(constraintGroupList) ;
constraintGroup.setItems(constraintGroupArray) ;

 

Now that we have our search criteria defined, we bundle them together into the MBSearchCriteria object required by mbCollectionAdvancedAssetSearchEx:

 

MBSearchCriteria searchCriteria = new MBSearchCriteria();
searchCriteria.setMaxHits(0) ;
searchCriteria.setSearchText("") ;
searchCriteria.setCBIRAssetID("");
searchCriteria.setRecursiveSearch(true) ;
searchCriteria.setSortAscOrder(false) ;
searchCriteria.setSortID("{00000000-0000-0000-0000-000000000000}") ;
searchCriteria.setStartingContainerID("{00000000-0000-0000-0000-000000000000}") ;
searchCriteria.setAdvancedSearchConstraintGroup(constraintGroup) ;
String tempCollection = vmb.mbCollectionAdvancedAssetSearchEx("Search_temp", searchCriteria) ;

 

If you wish to combine your search results with those obtained via the “open text” search, add the text you want to search over with the “setSearchText” method.  Note that the CBIRAssetID, RecursiveSearch, StartingContainerID and SortID are all reserved for future use and are not currently implemented. 

 

In my next posting, we’ll use the results of a search to demonstrate how to use MediaBin’s Asset APIs to manipulate assets in HP MediaBin. 

 

If you missed my first two posts, catch up! You can find them here:

Digital Marketing: Leveraging the HP MediaBin APIs: Part 1 - Getting Started

Digital Marketing: Leveraging the HP MediaBin APIs: Part 2 – API Overview

 

#HPDMB

Leave a Comment

We encourage you to share your comments on this post. Comments are moderated and will be reviewed
and posted as promptly as possible during regular business hours

To ensure your comment is published, be sure to follow the Community Guidelines.

Be sure to enter a unique name. You can't reuse a name that's already in use.
Be sure to enter a unique email address. You can't reuse an email address that's already in use.
Type the characters you see in the picture above.Type the words you hear.
Search
Showing results for 
Search instead for 
Do you mean 
About the Author
David Roy has over 27 years of experience in Software Engineering, with expertise in the areas of Digital Asset Management, Image Science an...
Featured


Follow Us
The opinions expressed above are the personal opinions of the authors, not of HP. By using this site, you accept the Terms of Use and Rules of Participation.