Fetch

Introduction

The fetch function uses Factual's Core API Read to support rich read queries. It takes a hash-map as its argument, which specifies the full query. The only required entry is :table, which must be associated with a valid Factual table name. Optional query parameters, such as row filters and geolocation, are specified with further entries in q.

The fetch function returns a sequence of records, where each record is a hash-map representing a row of results. The returned sequence will have response metatada attached to it, which includes things like API version, status, and extra row count information if it was requested.

Examples

Find rows in the global places database in the United States:

(fetch :global {:filters {"country" "US"}})

Find rows in the restaurant database whose name begins with "Star" and return both the data and a total count of the matched rows:

(fetch :restaurants {:filters {:name {:$bw "Star"}} :include_count true})

Do a full-text search of the restaurant database for rows that match the terms "Coffee, Los Angeles":

(fetch :restaurants {:q "Coffee, Los Angeles"})

To support paging in your app, return rows 20-40 of the full-text search result above:

(fetch :restaurants {:q "Coffee, Los Angeles" :offset 20 :limit 20})

Return rows from the global places database with a name equal to "Stand" within 5000 meters of the specified lat/lng:

(fetch :places {:filters {:name "Stand"}
                :geo {:$circle {:$center [34.06018, -118.41835] :$meters 5000}}})

Count all businesses in Chiang Mai, Thailand that are operational and have a telephone number:

(get-in
  (meta
      (fetch :global {:include_count true
                      :filters {:country {:$eq "TH"}
                                :region {:$eq "Chiang Mai"}
                                :status {:$eq 1}
                                :tel {:$blank false}}}))
      [:response :total_row_count])

Define a function that finds restaurants near a given latitude/longitude that deliver dinner, sorted by distance:

(defn deliver-dinner [lat lon]
  (fetch :restaurants {:filters {:meal_dinner {:$eq true}
                                    :meal_deliver {:$eq true}}
                          :geo {:$circle {:$center [lat lon] :$meters 4500}}
                          :sort :$distance}))

You could use the above function like so:

(deliver-dinner 34.039792 -118.423421)

Use fetch with any Factual dataset

The fetch function allows you to query any valid Factual dataset. E.g.:

(fetch :global {:limit 12})
(fetch :places {:q "starbucks"})
(fetch :restaurants {:filters {:locality "Los Angeles"}})
(fetch :products-cpg {:filters {:brand "The Body Shop"}})

Variations of fetch

For added convenience, and better composability, the fetch function supports several other argument variations. See the source level doc string on fetch for more details.