Open Semantic Framework PHP API  3.0
 All Data Structures Namespaces Files Functions Variables Pages
SearchQuery Class Reference

The Search Web service is used to perform full text searches on the structured data indexed on a OSF instance. More...

Inheritance diagram for SearchQuery:

Public Member Functions

 __construct ($network, $appID, $apiKey, $userID)
 Constructor. More...
 
 query ($query)
 Set the keywords to use for this search query. More...
 
 typesFilters ($types)
 Set all the type filters to use for this search query. More...
 
 typeFilter ($type)
 Add a type filter to use for this search query. More...
 
 typeBoost ($type, $boostModifier)
 Modifying the score of the results returned by the Search endpoint by boosting the results that have that type, and boosting it by the modifier weight. More...
 
 datasetsFilters ($datasets)
 Set all the dataset filters to use for this search query. More...
 
 datasetFilter ($dataset)
 Add a dataset filter to use for this search query. More...
 
 datasetBoost ($dataset, $boostModifier)
 Modifying the score of the results returned by the Search endpoint by boosting the results that have that dataset, and boosting it by the modifier weight. More...
 
 attributesValuesFilters ($attributes="all")
 Set all the attribute/value filters to use for this search query. More...
 
 attributeValueBoost ($attribute, $boostModifier, $value="", $valueIsUri=FALSE)
 Modifying the score of the results returned by the Search endpoint by boosting the results that have that attribute/value, and boosting it by the modifier weight. More...
 
 attributePhraseBoost ($attribute, $boostModifier)
 Modifying the score of the results returned by the Search endpoint by boosting the results where the field has all keywords within the distance defined by phraseDistance(). More...
 
 phraseBoostDistance ($distance)
 Define the maximum distance between the keywords of the search query that is used by the attributePhraseBoost(). More...
 
 attributeValuesFilters ($attribute, $values= '')
 Set an attribute/value(s) filter to use for this search query. More...
 
 setAttributesBooleanOperatorToOr ()
 Set the attributes boolean operator to OR. More...
 
 lang ($lang= 'en')
 Set the language of the records to be returned by the search endpoint. More...
 
 setAttributesBooleanOperatorToAnd ()
 Set the attributes boolean operator to AND. More...
 
 includeAttributes ($attributes)
 Set a list of attribute URIs to include in the resultset returned by the search endpoint. More...
 
 includeAttribute ($attribute)
 Set an attribute URI to include in the resultset returned by the search endpoint. More...
 
 includeNoAttributes ()
 Specify that no attributes should be returned by the query. More...
 
 items ($items)
 Set the number of items to return in a single resultset. More...
 
 page ($page)
 Set the offset of the resultset to return. More...
 
 enableInference ()
 Enable the inference for this query. More...
 
 disableInference ()
 Disable the inference for this query. More...
 
 defaultOperatorAND ()
 Set the default search query operator to AND. More...
 
 defaultOperatorOR ($constrains)
 Set the default search query operator to OR. More...
 
 excludeAggregates ()
 Exclude the aggregate records in the resultset of this query. More...
 
 includeAggregates ()
 Include the aggregate records in the resultset of this query. More...
 
 aggregateAttributes ($attributes)
 Specify a set of attributes URI for which we want their aggregated values. More...
 
 aggregateAttribute ($attribute)
 Specify an attribute URI for which we want its aggregated values. More...
 
 setAggregateAttributesObjectTypeToLiteral ()
 Determines that the aggregated value returned by the endpoint is a literal. More...
 
 setAggregateAttributesObjectTypeToUriLiteral ()
 Determines that the aggregated value returned by the endpoint is a URI and a Literal. More...
 
 setAggregateAttributeObjectTypeToUri ()
 Determines that the aggregated value returned by the endpoint is a URI. More...
 
 numberOfAggregateAttributesObject ($nb)
 
 distanceFilter ($lat, $long, $distance, $distanceType="km")
 The distance filter is a series of parameter that are used to filter records of the dataset according to the distance they are located from a given lat;long point. More...
 
 rangeFilter ($topLeftLat, $topLeftLong, $bottomRightLat, $bottomRightLong)
 The range filter is a series of parameter that are used to filter records of the dataset according to a rectangle bounds they are located in given their lat;long position. More...
 
 sort ($sortProperty, $sortOrder)
 Add a sort criteria to the Search query. More...
 
 extendedFilters ($filters)
 Extended filters are used to define more complex search filtered searches. More...
 
 includeScores ()
 Include the scores of the results into the resultset. More...
 
 excludeScores ()
 Exclude the scores of the results into the resultset. More...
 
 includeSpellcheck ()
 Includes the spellchecking suggestions to the resultset in the case that the resultset is empty. More...
 
 excludeSpellcheck ()
 Includes the spellchecking suggestions to the resultset even if the resultset is empty. More...
 
 searchRestriction ($property, $boost=1)
 Include the scores of the results into the resultset. More...
 
 recordsLocationAggregator ($lat, $long)
 Specifies a lat/long location where all the results should be aggregated around. More...
 

Detailed Description

The Search Web service is used to perform full text searches on the structured data indexed on a OSF instance.

A search query can be as simple as querying the data store for a single keyword, or to query it using a series of complex filters. Each search query can be applied to all, or a subset of, datasets accessible by the requester. All of the full text queries comply with the Lucene querying syntax.

Each Search query can be filtered by these different filtering criteria:

  • Type of the record(s) being requested
  • Dataset where the record(s) got indexed
  • Presence of an attribute describing the record(s)
  • A specific value, for a specific attribute describing the record(s)
  • A distance from a lat/long coordinate (for geo-enabled OSF instance)
  • A range of lat/long coordinates (for geo-enabled OSF instance)

Here is a code example of how this class can be used by developers:

// Use the SearchQuery class
// Create the SearchQuery object
$search = new SearchQuery("http://demo.citizen-dan.org/ws/");
// Set the query parameter with the search keyword "elm"
$search->query("school");
// Send the search query to the endpoint
$search->send();
// Get back the resultset returned by the endpoint
$resultset = $search->getResultset();
// Print different serializations for that resultset
print_r($resultset->getResultset());
See also
http://wiki.opensemanticframework.org/index.php/Search
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 56 of file SearchQuery.php.

Constructor & Destructor Documentation

__construct (   $network,
  $appID,
  $apiKey,
  $userID 
)

Constructor.

Parameters
mixed$networkOSF network where to send this query. Ex: http://localhost/ws/
mixed$appIDThe Application ID of the instance instance to key. The APP-ID is related to the API-KEY
mixed$apiKeyThe API Key of the OSF web service endpoints
mixed$userIDThe ID of the user that is doing the query

Definition at line 66 of file SearchQuery.php.

Member Function Documentation

aggregateAttribute (   $attribute)

Specify an attribute URI for which we want its aggregated values.

This is used to get a list of values, and their counts for a given attribute.

Optional: This function could be called before sending the query

Parameters
mixed$attributeAttribute URI for which we want its aggregates
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 808 of file SearchQuery.php.

aggregateAttributes (   $attributes)

Specify a set of attributes URI for which we want their aggregated values.

This is used to get a list of values, and their counts for a given attribute.

Optional: This function could be called before sending the query

Parameters
mixed$attributesArray of attributes URI for which we want their aggregates
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 783 of file SearchQuery.php.

attributePhraseBoost (   $attribute,
  $boostModifier 
)

Modifying the score of the results returned by the Search endpoint by boosting the results where the field has all keywords within the distance defined by phraseDistance().

Parameters
mixed$attributeAttribute URI to boost
mixed$boostModifierScore modifier weight. Score modifier can be quite small like 0.0001, or quite big like 10000.
Returns
SearchQuery

Definition at line 401 of file SearchQuery.php.

attributesValuesFilters (   $attributes = "all")

Set all the attribute/value filters to use for this search query.

Optional: This function could be called before sending the query

Parameters
mixed$attributesArray of attribute/value filters. If the value is "all", then the query will only filter on the attribute's URI. This param array looks like:

Array("attribute-uri-1" => array("value-to-filter"), ...)

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 323 of file SearchQuery.php.

attributeValueBoost (   $attribute,
  $boostModifier,
  $value = "",
  $valueIsUri = FALSE 
)

Modifying the score of the results returned by the Search endpoint by boosting the results that have that attribute/value, and boosting it by the modifier weight.

Parameters
mixed$attributeAttribute URI to boost
mixed$boostModifierScore modifier weight. Score modifier can be quite small like 0.0001, or quite big like 10000.
mixed$valueOptional specific value to boost for the given attribute URI
boolean$valueIsUriSpecify if the value for this attribute has to be considered a URI (this should be specified to TRUE if the attribute is an object property)
Returns
SearchQuery

Definition at line 374 of file SearchQuery.php.

attributeValuesFilters (   $attribute,
  $values = '' 
)

Set an attribute/value(s) filter to use for this search query.

Optional: This function could be called before sending the query

Parameters
mixed$attributeAttribute URI of the filter
mixed$valuesA single value, or an array of values for which we want to filter the search query
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 441 of file SearchQuery.php.

datasetBoost (   $dataset,
  $boostModifier 
)

Modifying the score of the results returned by the Search endpoint by boosting the results that have that dataset, and boosting it by the modifier weight.

Parameters
mixed$datasetDataset URI to boost
mixed$boostModifierScore modifier weight. Score modifier can be quite small like 0.0001, or quite big like 10000.
Returns
SearchQuery

Definition at line 291 of file SearchQuery.php.

datasetFilter (   $dataset)

Add a dataset filter to use for this search query.

Optional: This function could be called before sending the query

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Parameters
mixed$datasetA datasets URI to use to filter the returned results.
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 254 of file SearchQuery.php.

datasetsFilters (   $datasets)

Set all the dataset filters to use for this search query.

Optional: This function could be called before sending the query

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Parameters
mixed$datasetsAn array of datasets URI to use to filter the returned results.
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 223 of file SearchQuery.php.

defaultOperatorAND ( )

Set the default search query operator to AND.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 715 of file SearchQuery.php.

defaultOperatorOR (   $constrains)

Set the default search query operator to OR.

Parameters
$constrainsMinimal number of words that should be present in the returned records. More complex behaviors can be defined, the full syntax is explained in this document: http://lucene.apache.org/solr/4_1_0/solr-core/org/apache/solr/util/doc-files/min-should-match.html
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 734 of file SearchQuery.php.

disableInference ( )

Disable the inference for this query.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 701 of file SearchQuery.php.

distanceFilter (   $lat,
  $long,
  $distance,
  $distanceType = "km" 
)

The distance filter is a series of parameter that are used to filter records of the dataset according to the distance they are located from a given lat;long point.

Optional: This function could be called before sending the query

Parameters
mixed$latLatitude of the point of origin
mixed$longLongitude of the point of origin
mixed$distanceThe distance from the point of origin
mixed$distanceTypeOne of: "km" or "mile"
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 899 of file SearchQuery.php.

enableInference ( )

Enable the inference for this query.

This is the default behavior of this service.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 687 of file SearchQuery.php.

excludeAggregates ( )

Exclude the aggregate records in the resultset of this query.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 748 of file SearchQuery.php.

excludeScores ( )

Exclude the scores of the results into the resultset.

Definition at line 1037 of file SearchQuery.php.

excludeSpellcheck ( )

Includes the spellchecking suggestions to the resultset even if the resultset is empty.

Definition at line 1058 of file SearchQuery.php.

extendedFilters (   $filters)

Extended filters are used to define more complex search filtered searches.

This parameter uses a more complex syntax which enable the grouping of filter criterias and the usage of the AND, OR and NOT boolean operators. The grouping is done with the parenthesis. Each filter is composed of a url-encoded attribute URI to use as filters, followed by a colomn and the value to filter with. The full lucene syntax can be used to define the value to filter. If all values are required, the "*" (star) operator should be used as the value. If the value of an attribute needs to be considered a URI, then the "[uri]" syntax should be added at the end of the attribute filter like: "http%3A%2F%2Fpurl.org%2Fontology%2Ffoo%23friend[uri]:http%3A%2F%2Fbar.com%2Fmy-friend-uri". That way, the value of that attribute filter will be handled as a URI. There are a series of core attributes that can be used without specifying their full URI: dataset, type, inferred_type, prefLabel, altLabel, lat, long, description, polygonCoordinates, polylineCoordinates and located in. The extended filters are not a replacement to the attributes, types and datasets filtering parameters, they are an extension of it. Subsequent filtering criterias can be defined in the extended filtering parameter. The resolution logic by the Search endpoint is: attributes AND datasets AND types AND extended-filters. An example of such an extended query is: (http%3A%2F%2Fpurl.org%2Fontology%2Firon%23prefLabel:cancer AND NOT (breast OR ovarian)) AND (http%3A%2F%2Fpurl.org%2Fontology%2Fnhccn%23useGroupSignificant[uri]: (http%3A%2F%2Fpurl.org%2Fontology%2Fdoha%23liver_cancer OR http%3A%2F%2Fpurl.org%2Fontology%2Fdoha%23cancers_by_histologic_type)) AND dataset:"file://localhost/data/ontologies/files/doha.owl"

Note: both the URI and the value (all kind of values: literals and URIs) need to be URL encoded before being sent to the Search endpoint.

Parameters
mixed$filtersExtended filters query to use for this Search query.
Returns
SearchQuery

Definition at line 1011 of file SearchQuery.php.

includeAggregates ( )

Include the aggregate records in the resultset of this query.

This is the default behavior of this service.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 764 of file SearchQuery.php.

includeAttribute (   $attribute)

Set an attribute URI to include in the resultset returned by the search endpoint.

All the attributes used to defined the returned resultset that are not listed in this array will be ignored, and won't be returned by the endpoint. This is normally used when you know the properties you need for your application, and that you want to limit the bandwidth and minimize the size of the resultset.

Optional: This function could be called before sending the query

Parameters
mixed$attributeAn attribute URI to see in the resultset
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 595 of file SearchQuery.php.

includeAttributes (   $attributes)

Set a list of attribute URIs to include in the resultset returned by the search endpoint.

All the attributes used to defined the returned resultset that are not listed in this array will be ignored, and won't be returned by the endpoint. This is normally used when you know the properties you need for your application, and that you want to limit the bandwidth and minimize the size of the resultset.

Optional: This function could be called before sending the query

Parameters
mixed$attributesAn array of attribute URIs to see in the resultset
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 567 of file SearchQuery.php.

includeNoAttributes ( )

Specify that no attributes should be returned by the query.

The only two attributes that will be returned by the search endpoint are the URI and the Type of each result.

Optional: This function could be called before sending the query

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 624 of file SearchQuery.php.

includeScores ( )

Include the scores of the results into the resultset.

The score will be represented by the wsf:score property.

Definition at line 1027 of file SearchQuery.php.

includeSpellcheck ( )

Includes the spellchecking suggestions to the resultset in the case that the resultset is empty.

Definition at line 1048 of file SearchQuery.php.

items (   $items)

Set the number of items to return in a single resultset.

Default value is 10

Parameters
mixed$itemsThe number of items to return in a single resultset
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 642 of file SearchQuery.php.

lang (   $lang = 'en')

Set the language of the records to be returned by the search endpoint.

Only the textual information of the requested language will be returned to the user. If no textual information is available for a record, for a requested language, then only non-textual information will be returned about the record.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 528 of file SearchQuery.php.

numberOfAggregateAttributesObject (   $nb)

Definition at line 872 of file SearchQuery.php.

page (   $page)

Set the offset of the resultset to return.

By example, to get the item 90 to 100, this parameter should be set to 90.

Default page is 0

Parameters
mixed$pageThe offset of the resultset to return. By example, to get the item 90 to 100, this parameter should be set to 90.
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 666 of file SearchQuery.php.

phraseBoostDistance (   $distance)

Define the maximum distance between the keywords of the search query that is used by the attributePhraseBoost().

Parameters
mixed$distanceMaximum distance betweeen the search terms

Definition at line 422 of file SearchQuery.php.

query (   $query)

Set the keywords to use for this search query.

Optional: This function could be called before sending the query

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Parameters
mixed$queryKeywords to use to search for this query. Keywords can use some boolean operations. An empty string returns everything.
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 114 of file SearchQuery.php.

rangeFilter (   $topLeftLat,
  $topLeftLong,
  $bottomRightLat,
  $bottomRightLong 
)

The range filter is a series of parameter that are used to filter records of the dataset according to a rectangle bounds they are located in given their lat;long position.

Optional: This function could be called before sending the query

Parameters
mixed$topLeftLatLatitude of the top left corner of the bounding box
mixed$topLeftLongLongitude of the top left corner of the bounding box
mixed$bottomRightLatLatitude of the bottom right corner of the bounding box
mixed$bottomRightLongLongitude of the bottom right corner of the bounding box
See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 945 of file SearchQuery.php.

recordsLocationAggregator (   $lat,
  $long 
)

Specifies a lat/long location where all the results should be aggregated around.

For example, if we have a set of results compromised within a region. If we don't want the results spread everywhere in that region, we have to specify a location for this parameter such that all results get aggregated around that specific location within the region.

Parameters
$incTRUE if you want to include Scores, FALSE otherwise

Definition at line 1098 of file SearchQuery.php.

searchRestriction (   $property,
  $boost = 1 
)

Include the scores of the results into the resultset.

The score will be represented by the wsf:score property.

Parameters
$incTRUE if you want to include Scores, FALSE otherwise

Definition at line 1072 of file SearchQuery.php.

setAggregateAttributeObjectTypeToUri ( )

Determines that the aggregated value returned by the endpoint is a URI.

If the value of the attribute(s) is a URI (a reference to some record) then that URI will be returned as the aggregated value.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 865 of file SearchQuery.php.

setAggregateAttributesObjectTypeToLiteral ( )

Determines that the aggregated value returned by the endpoint is a literal.

If the value is a URI (a reference to some record), then the literal value will be the preferred label of that referred record.

This is the default behavior of this service.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 835 of file SearchQuery.php.

setAggregateAttributesObjectTypeToUriLiteral ( )

Determines that the aggregated value returned by the endpoint is a URI and a Literal.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 849 of file SearchQuery.php.

setAttributesBooleanOperatorToAnd ( )

Set the attributes boolean operator to AND.

If you have multiple attribute/value filters defined for this search query, then the Search endpoint will AND all of them.

This is the default behavior of this service.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 545 of file SearchQuery.php.

setAttributesBooleanOperatorToOr ( )

Set the attributes boolean operator to OR.

If you have multiple attribute/value filters defined for this search query, then the Search endpoint will OR all of them.

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 511 of file SearchQuery.php.

sort (   $sortProperty,
  $sortOrder 
)

Add a sort criteria to the Search query.

Parameters
mixed$sortPropertyProperty to sort on. Can be: "type", "uri", "dataset", "score", "preflabel" or any other url-encoded attribute URIs that are defined with a maximum cardinality of 1.
mixed$sortOrderOrder of the sort for that property. Can be "desc" or "asc"
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 962 of file SearchQuery.php.

typeBoost (   $type,
  $boostModifier 
)

Modifying the score of the results returned by the Search endpoint by boosting the results that have that type, and boosting it by the modifier weight.

Parameters
mixed$typeType URI to boost
mixed$boostModifierScore modifier weight. Score modifier can be quite small like 0.0001, or quite big like 10000.
Returns
SearchQuery

Definition at line 195 of file SearchQuery.php.

typeFilter (   $type)

Add a type filter to use for this search query.

Optional: This function could be called before sending the query

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Parameters
mixed$typeA type URI to use to filter the returned results.
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 163 of file SearchQuery.php.

typesFilters (   $types)

Set all the type filters to use for this search query.

Optional: This function could be called before sending the query

See also
http://wiki.opensemanticframework.org/index.php/Search#Web_Service_Endpoint_Information
Parameters
mixed$typesAn array of types URI to use to filter the returned results.
Author
Frederick Giasson, Structured Dynamics LLC.

Definition at line 132 of file SearchQuery.php.