From 18445d7755304d180be32b5621a339f9dc413687 Mon Sep 17 00:00:00 2001 From: Andy Eschbacher Date: Fri, 22 Apr 2016 21:19:55 -0400 Subject: [PATCH] adding better comments and tidying up code --- src/pg/sql/44_observatory_geometries.sql | 96 ++++++++++++++++++------ 1 file changed, 74 insertions(+), 22 deletions(-) diff --git a/src/pg/sql/44_observatory_geometries.sql b/src/pg/sql/44_observatory_geometries.sql index a7f8523..2347365 100644 --- a/src/pg/sql/44_observatory_geometries.sql +++ b/src/pg/sql/44_observatory_geometries.sql @@ -1,19 +1,34 @@ --- Returns the polygon(s) that overlap with the input geometry. --- Input: --- :param geom geometry: input geometry --- :param boundary_id text: table to get polygon from (can be approximate name) --- :param use_literal boolean: use the literal table name (defaults to true) +-- Data Observatory -- Welcome to the Future +-- These Data Observatory functions provide access to boundary polyons (and +-- their ids) such as those available through the US Census Tiger, Who's on +-- First, the Spanish Census, and so on --- From an input point geometry, find the boundary which intersects with the centroid of the input geometry + +-- OBS_GetGeometry +-- +-- Returns the boundary polygon(s) that overlap with the input point geometry. +-- From an input point geometry, find the boundary which intersects with the +-- centroid of the input geometry +-- Inputs: +-- geom geometry: input point geometry +-- boundary_id text: source id of boundaries +-- see function OBS_ListGeomColumns for all avaiable +-- boundary ids +-- time_span text: time span that the geometries were collected (optional) +-- +-- Output: +-- boundary geometry: geometry boundary that intersects with geom, is at the +-- resolution requested with boundary_id, and time_span +-- CREATE OR REPLACE FUNCTION cdb_observatory.OBS_GetGeometry( - geom geometry(geometry, 4326), + geom geometry(Geometry, 4326), boundary_id text, time_span text DEFAULT NULL) -RETURNS geometry(geometry, 4326) +RETURNS geometry(Geometry, 4326) AS $$ DECLARE - boundary geometry(geometry, 4326); + boundary geometry(Geometry, 4326); target_table text; BEGIN @@ -31,15 +46,18 @@ BEGIN SELECT x.target_tables INTO target_table FROM cdb_observatory._OBS_SearchTables(boundary_id, time_span) As x(target_tables, - time_spans) - ORDER BY x.time_spans DESC + timespans) + ORDER BY x.timespans DESC LIMIT 1; ELSE + -- TODO: modify for only one table returned instead of arbitrarily choosing + -- one with LIMIT 1 (could be conflict between clipped vs non-clipped + -- boundaries in the metadata tables) SELECT x.target_tables INTO target_table FROM cdb_observatory._OBS_SearchTables(boundary_id, time_span) As x(target_tables, - time_spans) - WHERE x.time_spans = time_span + timespans) + WHERE x.timespans = time_span LIMIT 1; END IF; @@ -66,6 +84,25 @@ BEGIN END; $$ LANGUAGE plpgsql; +-- OBS_GetGeometryId +-- +-- retrieves the boundary identifier (e.g., '36047' = Kings County/Brooklyn, NY) +-- corresponding to the location geom and boundary types (e.g., +-- us.census.tiger.county) + +-- Inputs: +-- geom geometry: location where the boundary is requested to overlap with +-- boundary_id text: source id of boundaries (e.g., us.census.tiger.county) +-- see function OBS_ListGeomColumns for all avaiable +-- boundary ids +-- time_span text: time span that the geometries were collected (optional) +-- +-- Output: +-- geometry_id text: identifier of the geometry which overlaps with the input +-- point geom in the table corresponding to boundary_id and +-- time_span +-- + CREATE OR REPLACE FUNCTION cdb_observatory.OBS_GetGeometryId( geom geometry(Geometry, 4326), boundary_id text, @@ -88,17 +125,17 @@ BEGIN IF time_span IS NULL THEN SELECT x.target_tables INTO target_table - FROM cdb_observatory.cdb_observatory._OBS_SearchTables(boundary_id, + FROM cdb_observatory._OBS_SearchTables(boundary_id, time_span) As x(target_tables, - time_spans) - ORDER BY x.time_spans DESC + timespans) + ORDER BY x.timespans DESC LIMIT 1; ELSE SELECT x.target_tables INTO target_table - FROM cdb_observatory.cdb_observatory._OBS_SearchTables(boundary_id, + FROM cdb_observatory._OBS_SearchTables(boundary_id, time_span) As x(target_tables, - time_spans) - WHERE x.time_spans = time_span + timespans) + WHERE x.timespans = time_span LIMIT 1; END IF; @@ -125,10 +162,25 @@ BEGIN END; $$ LANGUAGE plpgsql; --- Given a geometry reference (e.g., geoid for US Census), and it's geometry level (see OBS_ListGeomColumns() for all available boundary ids), give back the boundary that corresponds to that reference and level. --- @param geometry_id text: identifier for boundary geometry corresponding to a boundary id `boundary_id`. E.g., '36047' is a geoid for US Census Tiger boundaries corresponding to a county (047) in New York State (36) --- @param boundary_id: +-- OBS_GetGeometryById +-- +-- Given a geometry reference (e.g., geoid for US Census), and it's geometry +-- level (see OBS_ListGeomColumns() for all available boundary ids), give back +-- the boundary that corresponds to that geometry_id, boundary_id, and +-- time_span + +-- Inputs: +-- geometry_id text: geometry id of the requested boundary +-- boundary_id text: source id of boundaries (e.g., us.census.tiger.county) +-- see function OBS_ListGeomColumns for all avaiable +-- boundary ids +-- time_span text: time span that the geometries were collected (optional) +-- +-- Output: +-- boundary geometry: geometry boundary that matches geometry_id, is at the +-- resolution requested with boundary_id, and time_span +-- CREATE OR REPLACE FUNCTION cdb_observatory.OBS_GetGeometryById( geometry_id text, -- ex: '36047'