In tutorial 7, we already saw how to use the meta resource to retrieve collections by doing a search based on (parts of) tag(s). In this tutorial, we will look at these topics in further detail, using the PHP client libraries (see tutorial 2 for more details). The complete source code for this tutorial is also part of the client download package ('rass_tag_search.php'). You can try running it yourself, after having edited the named constants on top of the script.
Pre-Configuration
Before we start with the tutorial, we need do upload some files and attach tags to them. First, we create a directory 'tutorial9' on the CDN. Next, we upload six files and attach metadata to some of these files:
- 'eagle.mp4', which has been tagged with "animal", "bird" and "birdwatching"
- 'owl.mp4', which has been tagged with "animal", "bird" and "documentary"
- 'snake.mp4', which has been tagged with "animal", "reptile" and "documentary"
- 'spiderman.mp4', which has been tagged with "superhero", "rebirth" and "moviee"
- 'test1.mp4" without any tags
- 'test2.mp4" without any tags
Getting a META Feed
The getMetaFeed() function takes 2 arguments:
- $path : string containing the location of the file or directory for which metadata should be set.
- $query (= optional) : a Rass_MetaQuery object that acts as a wrapper for all query-string arguments
In the example below, we will call getMetaFeed() with a $path argument that points to the '/movies' directory and a query-string argument ('kind=file') that instructs RASS to only return entries concerning files.
$query = new Rass_MetaQuery("file");
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\nFound " . $entry->kind . " entry with path = " . $entry->path;
}
}
>> Found file entry with path = /tutorial9/eagle.mp4
>> Found file entry with path = /tutorial9/owl.mp4
>> Found file entry with path = /tutorial9/snake.mp4
>> Found file entry with path = /tutorial9/spiderman.mp4
>> Found file entry with path = /tutorial9/test1.mp4
>> Found file entry with path = /tutorial9/test2.mp4
As you can see, the meta feed contains an entry for each uploaded file, even if no metadata has been set. This is also the case when you pass the 'name' argument as query-string argument. For example:
$query = new Rass_MetaQuery("file");
$query->setName("test?.*");
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\nFound " . $entry->kind . " entry with path = " . $entry->path;
}
>> Found file entry with path = /tutorial9/test1.mp4
>> Found file entry with path = /tutorial9/test2.mp4
In this case, the file matching pattern only matches the 'test1.mp4' and 'test2.mp4' files. Note that you can not combine a name-based search with a metadata-based search in the same request.
Searches based on tag elements
The 'tag' query-string argument is not case-sensitive, but does require that you specify complete tags (no missing characters) as part of the query-string. Searches based on metadata can only return locations (files and/or directories) on which metadata has been set. Here's a basic example:
echo "\n\nSearch for all files tagged with 'bird' :";
$query->setSearchArg("tag", array("bird"));
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\n found " . $entry->kind . " entry with path = " . $entry->path;
}
>> Search for all files tagged with 'bird' :
>> found file entry with path = /tutorial9/eagle.mp4
>> found file entry with path = /tutorial9/owl.mp4
You can also use multiple 'tag' values to search on:
echo "\n\nSearch for all files tagged with 'bird' OR 'reptile' :";
$query->setSearchArg("tag", array("bird", "reptile"));
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\n found " . $entry->kind . " entry with path = " . $entry->path;
}
>> Search for all files tagged with 'bird' OR 'reptile' :
>> found file entry with path = /tutorial9/eagle.mp4
>> found file entry with path = /tutorial9/owl.mp4
>> found file entry with path = /tutorial9/snake.mp4
USING SEARCH OPERATORS
As explained in tutorial 7, RASS supports search operators (OR, AND, NOT) when doing metadata-based searches. In the two previous examples, the OR-operator (= default) has been used implicitly. To use another operator, you have to include it in your query-string. This can be done by using the setSearchArg() function of the $query object, which takes 4 parameters:
- $argname : string containing the search argument name (= tag', 'qtag', 'iqtag', 'meta', 'qmeta' or 'iqmeta')
- $or_args : array of argument values (= strings) to be used with the OR-operator
- $and_args : array of argument values (= strings) to be used with the AND-operator
- $not_args : array of argument values (= strings) to be used with the NOT-operator
The following example will use the AND-operator (+ character, URL encoded as %2B), which will result in a query-string like "tag=%2Banimal,%2Bdocumentary".
echo "\n\nSearch for all files tagged with 'animal' AND 'documentary' :";
$query->setSearchArg("tag", array(), array("animal", "documentary"));
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\n found " . $entry->kind . " entry with path = " . $entry->path;
}
>> Search for all files tagged with 'animal' AND 'documentary' :
>> found file entry with path = /tutorial9/owl.mp4
>> found file entry with path = /tutorial9/snake.mp4
Operators may also be combined. Here's a request for all files that must have the 'animal' tag, but may not have the 'bird' tag.
echo "\n\nSearch for all files tagged with 'animal' BUT NOT with 'bird' :";
$query->setSearchArg("tag", array("animal"), array(), array("bird"));
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\n found " . $entry->kind . " entry with path = " . $entry->path;
}
>> Search for all files tagged with 'animal' BUT NOT with 'bird' :
>> found file entry with path = /tutorial9/snake.mp4
Searching on part(s) of a tag
The 'qtag' (= case sensitive) and 'iqtag' (= case insensitive) allow you do searches on part of a tag. For instance:
echo "\n\nCase-sensitive search for all files with a tag that contains the string 'ani' :";
$query = new Rass_MetaQuery("file");
$query->setSearchArg("qtag", array("ani"));
$feed = $rass->getMetaFeed($dir_entry->path, $query);
foreach ($feed as $entry) {
echo "\n found " . $entry->kind . " entry with path = " . $entry->path;
}
>> Case-sensitive search for all files with a tag that contains the string 'ani' :
>> found file entry with path = /tutorial9/eagle.mp4
>> found file entry with path = /tutorial9/owl.mp4
>> found file entry with path = /tutorial9/snake.mp4
The same search operators as for the 'tag' argument apply here. However, it is not possible to combine 'tag', 'qtag' and/or 'iqtag' in a single request. If both the 'tag' and 'iqtag' arguments are part of a single query-string, the 'iqtag' argument will be ignored. For more examples, see the tutorial's PHP script and the Rambla wiki pages.
