com.factual.driver
Class Query

java.lang.Object
  com.factual.driver.Query

public class Query
extends Object

Represents a top level Factual query. Knows how to represent the query as URL encoded key value pairs, ready for the query string in a GET request. (See toUrlQuery())

Author:

aaron

Constructor Summary

Query()

Method Summary

void	add(Filter filter) Adds filter to this Query.
Query	and(Query... queries) Used to nest AND'ed predicates.
QueryBuilder	criteria(String field) Deprecated. use field(String)
QueryBuilder	field(String field) Begins construction of a new row filter for this Query.
String[]	getSelectFields()
Query	includeRowCount() The response will include a count of the total number of rows in the table that conform to the request based on included filters.
Query	includeRowCount(boolean includeRowCount) When true, the response will include a count of the total number of rows in the table that conform to the request based on included filters.
Query	limit(long limit) Sets the maximum amount of records to return from this Query.
Query	near(String text, int meters)
Query	offset(long offset) Sets how many records in to start getting results (i.e., the page offset) for this Query.
Query	only(String... fields) Sets the fields to select.
Query	or(Query... queries) Used to nest OR'ed predicates.
Query	search(String term) Sets a full text search query.
Query	sortAsc(String field) Sets this Query to sort field in ascending order.
Query	sortDesc(String field) Sets this Query to sort field in descending order.
String	toString()
protected String	toUrlQuery() Builds and returns the query string to represent this Query when talking to Factual's API.
Query	within(Circle circle) Adds a filter so that results can only be (roughly) within the specified geographic circle.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Query

public Query()

Method Detail

search

public Query search(String term)

Sets a full text search query. Factual will use this value to perform a full text search against various attributes of the underlying table, such as entity name, address, etc.

Parameters:

term - the text for which to perform a full text search.

Returns:

this Query

limit

public Query limit(long limit)

Sets the maximum amount of records to return from this Query.

Parameters:

limit - the maximum amount of records to return from this Query.

Returns:

this Query

only

public Query only(String... fields)

Sets the fields to select. This is optional; default behaviour is generally to select all fields in the schema.

Parameters:

fields - the fields to select.

Returns:

this Query

getSelectFields

public String[] getSelectFields()

Returns:

array of select fields set by only(), null if none.

sortAsc

public Query sortAsc(String field)

Sets this Query to sort field in ascending order.

Parameters:

field - the field to sort in ascending order.

Returns:

this Query

sortDesc

public Query sortDesc(String field)

Sets this Query to sort field in descending order.

Parameters:

field - the field to sort in descending order.

Returns:

this Query

offset

public Query offset(long offset)

Sets how many records in to start getting results (i.e., the page offset) for this Query.

Parameters:

offset - the page offset for this Query.

Returns:

this Query

includeRowCount

public Query includeRowCount()

The response will include a count of the total number of rows in the table that conform to the request based on included filters. This will increase the time required to return a response. The default behavior is to NOT include a row count.

Returns:

this Query, marked to return total row count when run.

includeRowCount

public Query includeRowCount(boolean includeRowCount)

When true, the response will include a count of the total number of rows in the table that conform to the request based on included filters. Requesting the row count will increase the time required to return a response. The default behavior is to NOT include a row count.

Parameters:

includeRowCount - true if you want the results to include a count of the total number of rows in the table that conform to the request based on included filters.

Returns:

this Query.

criteria

@Deprecated
public QueryBuilder criteria(String field)

Deprecated. use field(String)

Begins construction of a new row filter.

Parameters:

field - the name of the field on which to filter.

Returns:

A partial representation of the new row filter.

field

public QueryBuilder field(String field)

Begins construction of a new row filter for this Query.

Parameters:

field - the name of the field on which to filter.

Returns:

A partial representation of the new row filter.

near

public Query near(String text,
                  int meters)

within

public Query within(Circle circle)

Adds a filter so that results can only be (roughly) within the specified geographic circle.

Parameters:

circle - The circle within which to bound the results.

Returns:

this Query.

and

public Query and(Query... queries)

Used to nest AND'ed predicates.

or

public Query or(Query... queries)

Used to nest OR'ed predicates.

add

public void add(Filter filter)

Adds filter to this Query.

toUrlQuery

protected String toUrlQuery()

Builds and returns the query string to represent this Query when talking to Factual's API. Provides proper URL encoding and escaping.

Example output:

 filters=%7B%22%24and%22%3A%5B%7B%22region%22%3A%7B%22%24in%22%3A%22MA%2CVT%2CNH%22%7D%7D%2C%7B%22%24or%22%3A%5B%7B%22first_name%22%3A%7B%22%24eq%22%3A%22Chun%22%7D%7D%2C%7B%22last_name%22%3A%7B%22%24eq%22%3A%22Kok%22%7D%7D%5D%7D%5D%7D
 

(After decoding, the above example would be used by the server as:)

 filters={"$and":[{"region":{"$in":"MA,VT,NH"}},{"$or":[{"first_name":{"$eq":"Chun"}},{"last_name":{"$eq":"Kok"}}]}]}
 

Returns:

the query string to represent this Query when talking to Factual's API.

toString

public String toString()

Overrides:

toString in class Object