Class::DBI::ConceptSearch - Retrieve Class::DBI aggregates from high-level conceptual searches
my $cs = Class::DBI::ConceptSearch->new(xml => $config); #see CONFIGURATION $cs->use_wildcards(1); $cs->use_implicit_wildcards(1); $cs->use_search_ilike(1); $cs->use_search_lower(1); my(@tracks) = $cs->search( albums => 'Britney' );
Given the example Class::DBI classes (Music::CD, Music::Artist, Music::Track), lets add another one, Music::Dbxref, which contains external database accessions outside our control. Music::Dbxref includes things like UPC IDs, ASIN and ISBN numbers, vendor and manufacturer part numbers, person IDs (for artists), etc.
Now, imagine a website with a basic search function that gives the users the option of searching in "Albums", "Artists", "Tracks", and (my favorite) "Anything".
(1) In a simple implementation, a user search for "Britney Spears" in "Artists" is going to do something like:
Music::Artist->search( name => 'Britney Spears');
(2) But suppose the user had accidentally searched in "Albums". The executed search would be:
Music::CD->search( title => 'Britney Spears');
which doesn't produce any hits, and wouldn't even using search_like(). Doh!
(3) Likewise, if the user were to search in *any* category for Britney's CD "In the Zone" by its ASIN B0000DD7LB, no hits would be found.
In a slightly more complex implementation, searches in each category might try to match fields in multiple different tables. Query (2) might try to match "Britney Spears" in both Artist.name and CD.title, but this would be hardcoded into a class that performs the search. If the search should be returning only CDs, we would also have to hardcode how to transform any matching Music::Artist instance to Music::CD instance(s).
This is where Class::DBI::ConceptSearch comes in. It contains a generic search function that, given a configuration file, allows arbitrary mappings of search categories to database table fields. You specify what the available categories are, and where to look for data when a category is searched.
You also specify any transforms that need to be performed on the resulting matches. This is where the Artist->CD mapping in query (2) is set up.
You're also able to search in sections of the database which are private internals, and return public data. For instance, in query (3), we might have searched in "Artist" for the ASID. Behind the scenes, Class::DBI::ConceptSearch finds the ID and follows up with a:
Dbxref -> CD -> Artist
transform and returns the Music::Artist objects.
As we can imagine, there may be multiple possible paths within the database between Dbxref and Artist. It is also possible to specify these, see CONFIGURATION for details on how to define multiple sources
NOTE: This example is contrived, and the usefulness of
Concept -> Table.Field(s)
mapping may not be readily apparent. Class::DBI::ConceptSearch really shines when you have a more complex data model.
<?xml version="1.0" encoding="UTF-8"?> <conceptsearch page_size="20"> <!-- Find artists with name matching search term --> <concept label="Artist" name="artist"> <source class="Music::Artist" field="name"/> </concept> <!-- Find albums with title matching search term, -OR- artist with name matching search term, -OR- album with dbxref (ASIN, UPC, etc) matching search term --> <concept label="Album" name="cd"> <source class="Music::CD" field="title"/> <source class="Music::Artist" field="name"> <transform sourceclass="Music::Artist" sourcefield="artistid" targetclass="Music::CD" targetfield="artistid"/> </source> <source class="Music::Dbxref" field="accession"> <transform sourceclass="Music::Dbxref" sourcefield="dbxrefid" targetclass="Music::CD_Dbxref" targetfield="dbxrefid"/> <transform sourceclass="Music::CD_Dbxref" sourcefield="cdid" targetclass="Music::CD" targetfield="cdid"/> </source> </concept> <!-- Find songs matching search term -OR- songs by artist matching search term -OR- songs matching dbxref (iTunes ID, perhaps) --> <concept label="Song" name="track"> <source class="Music::Track" field="title"/> <source class="Music::Artist" field="name"> <transform sourceclass="Music::Artist" sourcefield="artistid" targetclass="Music::CD" targetfield="artistid"/> </source> <source class="Music::Dbxref" field="accession"> <transform sourceclass="Music::Dbxref" sourcefield="dbxrefid" targetclass="Music::Track_Dbxref" targetfield="dbxrefid"/> <transform sourceclass="Music::Track_Dbxref" sourcefield="trackid" targetclass="Music::Track" targetfield="trackid"/> </source> </concept> </conceptsearch>
conceptsearch # root container for searchable concepts attributes: name (optional) page_size (optional) # number of search results per page if the DBI object uses Class::DBI::Pager subelements: concept (0..*) concept # a searchable concept attributes: name (required) # name of the concept label (optional) # label of the concept, used for display UI, for # instance target (optional) # class of object returned by source subelements: source (0..*) source # class in which to search attributes: class (required) # name of class field (required) # attribute of class to match search pattern subelements: transform (0..*) transform # rule to transform one class to another ; an edge # between nodes # a sourceclass.sourcefield = targetclass.targetfield # join is performed attributes: sourceclass (required) # source class (defaults to parent source.class for # first <transform/> element sourcefield (required) # source field which equals target field targetclass (required) # target class returned targetfield (required) # target field which equals source field subelements: none
Email the author, or cdbi-talk@groups.kasei.com
Email the author.
Allen Day <allenday@ucla.edu>
Concept Mapping http://www.google.com/search?q=concept+mapping
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
Title : new Usage : my $obj = new Class::DBI::ConceptSearch(xml => $xml); Function: Builds a new Class::DBI::ConceptSearch object Returns : an instance of Class::DBI::ConceptSearch Args : xml (required): an xml string describing the behavior of this instance. See CONFIGURATION
Title : _init Usage : $obj->_init(%arg); Function: internal method. initializes a new Class::DBI::ConceptSearch object Returns : true on success Args : args passed to new()
Title : search Usage : $cs->search(concept => 'gene', pattern => 'GH1'); Function: Returns : a (possibly heterogenous) list of objects inheriting from Class::DBI. Args : concept (required): conceptual domain to be searched pattern (required): pattern to match in each source table.field of concept search, as configured. See CONFIGURATION
Title : pager Usage : $obj->pager($newval) Function: sets/returns the pager object, useful for getting information about the complete set of results Returns : value of pager Args : on set, new value (a scalar or undef, optional)
Title : use_wildcards Usage : $obj->use_wildcards($newval) Function: when true, enables search_like/search_ilike from search() Returns : value of use_wildcards (a scalar) Args : on set, new value (a scalar or undef, optional)
Title : use_implicit_wildcards Usage : $obj->use_implicit_wildcards($newval) Function: assume wildcards on the beginning and end of the search string Returns : value of use_implicit_wildcards (a scalar) Args : on set, new value (a scalar or undef, optional)
Title : use_search_ilike Usage : $obj->use_search_ilike($newval) Function: when true, search() uses search_ilike() where search_like() would have been used Returns : value of use_search_ilike (a scalar) Args : on set, new value (a scalar or undef, optional)
Title : use_search_lower Usage : $obj->use_search_lower($newval) Function: when true, search() uses search_lower() where search_like() would have been used Returns : value of use_search_lower (a scalar) Args : on set, new value (a scalar or undef, optional)
Title : xml Usage : $obj->xml($newval) Function: stores the configuration for this instance. See CONFIGURATION Returns : value of xml (a scalar) Args : on set, new value (a scalar or undef, optional)
To install Class::DBI::ConceptSearch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::DBI::ConceptSearch
CPAN shell
perl -MCPAN -e shell install Class::DBI::ConceptSearch
For more information on module installation, please visit the detailed CPAN module installation guide.