Query the Data Delivery Network
Query the DDNThe easiest way to query any data on Splitgraph is via the "Data Delivery Network" (DDN). The DDN is a single endpoint that speaks the PostgreSQL wire protocol. Any Splitgraph user can connect to it at data.splitgraph.com:5432 and query any version of over 40,000 datasets that are hosted or proxied by Splitgraph.
For example, you can query the asotin_county_library_district_services table in this repository, by referencing it like:
"wa-gov/asotin-county-library-district-services-j8pm-xq6k:latest"."asotin_county_library_district_services"or in a full query, like:
SELECT
":id", -- Socrata column ID
"virtref24_7", -- Is Virtual Reference Service provided 24 hours a day, 7 days a week?
"ematcirc", -- Electronic Materials Circulation, or annual number of check-outs or renewals of digital items (e.g., e-books) distributed online to authenticated library users for limited periods, and which can be accessed by a computer, tablet, mobile phone or e-book reader. Does not include database use. An empty cell means the figure was not reported that year.
"totalcirc", -- Total Circulation, or the annual number of library items checked out or renewed. Includes interlibrary loans checked out directly to a patron, but not those checked out to other libraries.
"virtvisits", -- Virtual visits. The annual number of users connecting to a networked library resource, such as the online public catalog or library website. Beginning in 2018, this category’s definition was clarified to include only visits to webpages on the library’s domain, not visits to library social media pages. This did not affect ACLD counts, which have never included social media site visits.
"wifisessions", -- Wireless Sessions, or the annual number of times patrons connect to the library’s wireless internet. An empty cell means the figure was not reported that year.
"physmatcirc", -- Physical Materials Circulation, or the annual number of check-outs or renewals of physical items such as books. Includes interlibrary loans checked out directly to a patron, but not those checked out to other libraries. An empty cell means the figure was not reported that year.
"year", -- Year represented, from Jan. 1 to Dec. 31.
"physvisits", -- Physical Visits. The annual number of people visiting library facilities in person, for any purpose.
"dbasesearch", -- Database searches, or the annual number of searches on licensed databases provided by the library. Does not include searches of free online resources.
"servpop", -- Service Population, including those living in areas legally designated to support the library through taxes or contracting fees.
"pubcompuses" -- Public Computer Uses, or the annual number of times patrons use the library’s public computers connected to the internet.
FROM
"wa-gov/asotin-county-library-district-services-j8pm-xq6k:latest"."asotin_county_library_district_services"
LIMIT 100;Connecting to the DDN is easy. All you need is an existing SQL client that can connect to Postgres. As long as you have a SQL client ready, you'll be able to query wa-gov/asotin-county-library-district-services-j8pm-xq6k with SQL in under 60 seconds.
Query Your Local Engine
bash -c "$(curl -sL https://github.com/splitgraph/splitgraph/releases/latest/download/install.sh)"Read the installation docs.
Splitgraph Cloud is built around Splitgraph Core (GitHub), which includes a local Splitgraph Engine packaged as a Docker image. Splitgraph Cloud is basically a scaled-up version of that local Engine. When you query the Data Delivery Network or the REST API, we mount the relevant datasets in an Engine on our servers and execute your query on it.
It's possible to run this engine locally. You'll need a Mac, Windows or Linux system to install sgr, and a Docker installation to run the engine. You don't need to know how to actually use Docker; sgrcan manage the image, container and volume for you.
There are a few ways to ingest data into the local engine.
For external repositories, the Splitgraph Engine can "mount" upstream data sources by using sgr mount. This feature is built around Postgres Foreign Data Wrappers (FDW). You can write custom "mount handlers" for any upstream data source. For an example, we blogged about making a custom mount handler for HackerNews stories.
For hosted datasets (like this repository), where the author has pushed Splitgraph Images to the repository, you can "clone" and/or "checkout" the data using sgr cloneand sgr checkout.
Cloning Data
Because wa-gov/asotin-county-library-district-services-j8pm-xq6k:latest is a Splitgraph Image, you can clone the data from Spltgraph Cloud to your local engine, where you can query it like any other Postgres database, using any of your existing tools.
First, install Splitgraph if you haven't already.
Clone the metadata with sgr clone
This will be quick, and does not download the actual data.
sgr clone wa-gov/asotin-county-library-district-services-j8pm-xq6kCheckout the data
Once you've cloned the data, you need to "checkout" the tag that you want. For example, to checkout the latest tag:
sgr checkout wa-gov/asotin-county-library-district-services-j8pm-xq6k:latestThis will download all the objects for the latest tag of wa-gov/asotin-county-library-district-services-j8pm-xq6k and load them into the Splitgraph Engine. Depending on your connection speed and the size of the data, you will need to wait for the checkout to complete. Once it's complete, you will be able to query the data like you would any other Postgres database.
Alternatively, use "layered checkout" to avoid downloading all the data
The data in wa-gov/asotin-county-library-district-services-j8pm-xq6k:latest is 0 bytes. If this is too big to download all at once, or perhaps you only need to query a subset of it, you can use a layered checkout.:
sgr checkout --layered wa-gov/asotin-county-library-district-services-j8pm-xq6k:latestThis will not download all the data, but it will create a schema comprised of foreign tables, that you can query as you would any other data. Splitgraph will lazily download the required objects as you query the data. In some cases, this might be faster or more efficient than a regular checkout.
Read the layered querying documentation to learn about when and why you might want to use layered queries.
Query the data with your existing tools
Once you've loaded the data into your local Splitgraph Engine, you can query it with any of your existing tools. As far as they're concerned, wa-gov/asotin-county-library-district-services-j8pm-xq6k is just another Postgres schema.