SQL Procedures API

Paid edition only. The compound procedures described below are available with the paid edition of Geo Data Connector. They are not included in the free edition.

Geo Data Connector provides four compound procedures that expose all application functionality directly from SQL. Use these to automate workflows, integrate with AI coding assistants, or manage data ingestion without launching the interactive application.

All compound procedures share the same signature:

CALL SETUP.<procedure>('<action>', <params>);

where <action> identifies the operation and <params> is a VARIANT (JSON object) containing action-specific parameters. Pass NULL when no parameters are needed.

Every call returns a JSON string with a consistent structure:

{"ok": true, "action": "list", "data": {...}, "error": null}

Use PARSE_JSON() to extract fields from the result.

Database Context

Before calling any procedure, set the active database to the Geo Data Connector application database. This is the database that was created when you installed the Connector — its name matches the name you chose during installation (visible in Snowsight under Catalog → Apps).

USE DATABASE GEO_DATA_CONNECTOR;

Replace GEO_DATA_CONNECTOR with your application database name. If you are unsure of the name, list your installed applications:

SHOW APPLICATIONS;

The name column shows the application database name to use.

Without setting the database context, calls to SETUP.<procedure> will fail because Snowflake cannot resolve the schema.

Output Formats

All procedures support two output formats:

Format	Signature	Returns	Best for
JSON (default)	CALL SETUP.<proc>('<action>', <params>)	JSON string	AI coding assistants, scripts, programmatic consumers
Tabular	CALL SETUP.<proc>('<action>', <params>, 'table')	Result set	Snowsight SQL worksheets, interactive use

The tabular format renders data as native columns in Snowsight:

-- JSON output (default)
CALL SETUP.GDC_TASK('list', NULL);

-- Tabular output (renders as a table in Snowsight)
CALL SETUP.GDC_TASK('list', NULL, 'table');

-- Tabular search results
CALL SETUP.GDC_DISCOVER('search', PARSE_JSON('{"q": "buildings Finland", "limit": 5}'), 'table');

The tabular format uses CALL syntax. The SELECT * FROM TABLE(...) syntax is not supported because tabular procedures use dynamic columns that vary by action.

Error Handling

When a call fails, ok is false and the error object contains a code and message:

{"ok": false, "action": "get_setting", "data": null, "error": {"code": "INVALID_PARAMETER", "message": "..."}}

Error Code	Meaning
UNKNOWN_ACTION	The action name is not recognized
MISSING_PARAMETER	A required parameter was not provided
INVALID_PARAMETER	A parameter value is not valid
NOT_FOUND	The requested resource does not exist
CONFIG_MISSING	A required configuration setting has not been set
NO_SCHEDULE	A schedule is required but was not provided
DISCOVERY_ERROR	The Connector could not reach the external data source
SEARCH_ERROR	The search request failed
INTERNAL_ERROR	An unexpected error occurred

Configuration (GDC_CONFIG)

Available to the APP_ADMIN role. Manages application settings and checks infrastructure status.

Actions

list_settings

Returns all user-facing configuration settings.

Parameters: None. Pass NULL.

Response: Array of {KEY, VALUE} objects.

CALL SETUP.GDC_CONFIG('list_settings', NULL);

get_setting

Returns a single setting by key.

Parameter	Required	Type	Description
key	Yes	string	The setting key to retrieve

Allowed keys: ingestion-database, notification-email, notify-task-success, notify-task-failure, notify-idle-warning, notify-auto-suspend, notify-idle-hours, auto-suspend-enabled, auto-suspend-timeout, app-edition, app-version, instance-id.

Returns INVALID_PARAMETER if the key is not in the allowed list. Returns null data if the key exists in the allowed list but has not been set.

CALL SETUP.GDC_CONFIG('get_setting', PARSE_JSON('{"key": "ingestion-database"}'));

set_setting

Creates or updates a setting.

Parameter	Required	Type	Description
key	Yes	string	The setting key to set
value	Yes	string	The value to assign

Writable keys: ingestion-database, notification-email, notify-task-success, notify-task-failure, notify-idle-warning, notify-auto-suspend, notify-idle-hours, auto-suspend-enabled, auto-suspend-timeout.

The keys app-edition, app-version, and instance-id are read-only and cannot be changed. Setting ingestion-database to a non-empty value also creates the database if it does not already exist.

Response: {OK: true, ERROR: null} on success.

-- Set the ingestion database
CALL SETUP.GDC_CONFIG('set_setting', PARSE_JSON('{"key": "ingestion-database", "value": "MY_GDC_DATA"}'));

-- Enable email notifications on task failure
CALL SETUP.GDC_CONFIG('set_setting', PARSE_JSON('{"key": "notify-task-failure", "value": "true"}'));

get_warehouse_status

Checks whether the compute warehouse is available.

Parameters: None. Pass NULL.

Response: {available: true|false}.

SELECT PARSE_JSON(SETUP.GDC_CONFIG('get_warehouse_status', NULL)):data:available::BOOLEAN;

get_eai_status

Checks whether External Access Integration is configured (required for discovery and ingestion).

Parameters: None. Pass NULL.

Response: {configured: true|false}.

SELECT PARSE_JSON(SETUP.GDC_CONFIG('get_eai_status', NULL)):data:configured::BOOLEAN;

get_auto_suspend_status

Returns the current auto-suspend configuration.

Parameters: None. Pass NULL.

Response: {enabled: true|false, timeout_minutes: integer, timeout_seconds: integer}.

CALL SETUP.GDC_CONFIG('get_auto_suspend_status', NULL);

Connections (GDC_CONNECTION)

Available to the APP_USER role. Manages saved data source connections.

Actions

count

Returns the number of saved connections.

Parameters: None. Pass NULL.

Response: {count: integer}.

SELECT PARSE_JSON(SETUP.GDC_CONNECTION('count', NULL)):data:count::INT;

list

Returns saved connections with pagination.

Parameter	Required	Type	Default	Description
page	No	integer	1	Page number (1-indexed)
length	No	integer	10	Rows per page
sortkey	No	string	NAME	Column to sort by
sortorder	No	string	asc	Sort direction: asc or desc

Response: Array of connection objects with fields: URI, TYPE, NAME_SERVICE, DESCRIPTION, DATASET_COUNT, AUTH_METHOD, ACCESSED, CREATED, MODIFIED.

CALL SETUP.GDC_CONNECTION('list', PARSE_JSON('{"page": 1, "length": 10}'));

upsert

Creates a new connection or updates an existing one. Connections are identified by their URI.

Parameter	Required	Type	Description
uri	Yes	string	The data source URL
type	Yes	string	Service type (e.g., WFS, WMS, WCS, WMTS, CSW)
name_service	No	string	Service name (as reported by the data source)
description	No	string	User-provided description
dataset_count	No	integer	Number of datasets in the service
auth_method	No	string	Authentication method: none (default) or basic
auth_username	No	string	Username or API key (write-only, stored encrypted)
auth_password	No	string	Password (write-only, stored encrypted, optional)

When auth_method is basic, auth_username is required for new connections. On updates, omitting auth_username or auth_password preserves the existing encrypted value. Credentials are never returned by list or any other read action.

Response: {rows_inserted: integer, rows_updated: integer}.

-- Connection without authentication
CALL SETUP.GDC_CONNECTION('upsert', PARSE_JSON('{
  "uri": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple",
  "type": "WFS",
  "name_service": "NLS Finland INSPIRE WFS"
}'));

-- Connection with API key authentication
CALL SETUP.GDC_CONNECTION('upsert', PARSE_JSON('{
  "uri": "https://avoin-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcapi/v1",
  "type": "OGC API Features",
  "name_service": "NLS Finland File Service",
  "auth_method": "basic",
  "auth_username": "your-api-key"
}'));

delete

Deletes a saved connection by URI.

Parameter	Required	Type	Description
uri	Yes	string	The connection URI to delete

Response: {rows_deleted: integer}.

CALL SETUP.GDC_CONNECTION('delete', PARSE_JSON('{"uri": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple"}'));

Tasks (GDC_TASK)

Available to the APP_USER role. Requires External Access Integration (connectivity to external data sources). Manages the full lifecycle of ingestion tasks — create, delete, suspend, resume, schedule — and provides read-only access to task details, run history, and table information.

Schedule Values

Schedule parameters accept one of three values (case-insensitive):

Value	Frequency
Daily	Once per day
Weekly	Once per week
Monthly	Once per month

The Connector converts these to Snowflake CRON expressions automatically.

Actions — Task Lifecycle

create

Creates an ingestion task for a data source. If a task already exists for the same source, it is recreated with a fresh state.

Parameter	Required	Type	Description
url	Yes	string	The data source URL
type	Yes	string	Service type (e.g., WFS, WMS, WCS, WMTS)
dataset	Yes	string	The dataset name within the service
schedule	No	string	Daily, Weekly, or Monthly. If omitted, the task is created but not scheduled.

Response: {name: string, enabled: boolean}. The name is a deterministic identifier derived from the source parameters. The enabled field is true only when a schedule is provided and registration succeeds.

Prerequisite: The ingestion-database setting must be configured via GDC_CONFIG('set_setting', ...) before creating tasks. Returns CONFIG_MISSING if not set.

-- Create a daily WFS ingestion task
CALL SETUP.GDC_TASK('create', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/bu_mtk_polygon",
  "type": "WFS",
  "dataset": "bu-core2d:Building",
  "schedule": "Daily"
}'));

-- Create a task without a schedule (manual execution only)
CALL SETUP.GDC_TASK('create', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/bu_mtk_polygon",
  "type": "WFS",
  "dataset": "bu-core2d:Building"
}'));

delete

Deletes a task, removes all associated Snowflake task objects, and deregisters the data source. Provide either the task name or the source identifiers.

Parameter	Required	Type	Description
name	Either name or all three source params	string	The task name
url		string	The data source URL
type		string	Service type
dataset		string	The dataset name

Response: {rows_deleted: integer}.

-- Delete by name
CALL SETUP.GDC_TASK('delete', PARSE_JSON('{"name": "INGESTION_927d79958453454b267925f28d4f4675"}'));

-- Delete by source identifiers
CALL SETUP.GDC_TASK('delete', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/bu_mtk_polygon",
  "type": "WFS",
  "dataset": "bu-core2d:Building"
}'));

suspend

Suspends a scheduled task and disables automatic ingestion.

Parameter	Required	Type	Description
name	Yes	string	The task name

Response: null. The task is disabled. If the task was not already in a terminal state, its status changes to INACTIVE.

CALL SETUP.GDC_TASK('suspend', PARSE_JSON('{"name": "INGESTION_927d79958453454b267925f28d4f4675"}'));

resume

Resumes a suspended task. Uses the task's existing schedule unless overridden.

Parameter	Required	Type	Description
name	Yes	string	The task name
schedule	No	string	Daily, Weekly, or Monthly. If omitted, uses the task's existing schedule. Returns NO_SCHEDULE if the task has no schedule and none is provided.

Response: {enabled: boolean}.

-- Resume with existing schedule
CALL SETUP.GDC_TASK('resume', PARSE_JSON('{"name": "INGESTION_927d79958453454b267925f28d4f4675"}'));

-- Resume with a new schedule
CALL SETUP.GDC_TASK('resume', PARSE_JSON('{"name": "INGESTION_927d79958453454b267925f28d4f4675", "schedule": "Weekly"}'));

set_schedule

Changes the schedule of an existing task. The task is briefly suspended and resumed with the new schedule.

Parameter	Required	Type	Description
name	Yes	string	The task name
schedule	Yes	string	Daily, Weekly, or Monthly

Response: {schedule: string, enabled: boolean}.

CALL SETUP.GDC_TASK('set_schedule', PARSE_JSON('{
  "name": "INGESTION_927d79958453454b267925f28d4f4675",
  "schedule": "Monthly"
}'));

unset_schedule

Removes the schedule from a task. The task is suspended and will only run when executed manually.

Parameter	Required	Type	Description
name	Yes	string	The task name

Response: null.

CALL SETUP.GDC_TASK('unset_schedule', PARSE_JSON('{"name": "INGESTION_927d79958453454b267925f28d4f4675"}'));

execute

Runs a task immediately, regardless of its schedule. The task's status changes to IN PROGRESS.

Parameter	Required	Type	Description
name	Yes	string	The task name

Response: {name: string}.

CALL SETUP.GDC_TASK('execute', PARSE_JSON('{"name": "INGESTION_927d79958453454b267925f28d4f4675"}'));

Actions — Task Information

count

Returns the number of ingestion tasks.

Parameters: None. Pass NULL.

Response: {count: integer}.

SELECT PARSE_JSON(SETUP.GDC_TASK('count', NULL)):data:count::INT AS task_count;

list

Returns ingestion tasks with pagination.

Parameter	Required	Type	Default	Description
page	No	integer	1	Page number (1-indexed)
length	No	integer	10	Rows per page
sortkey	No	string	TASK_NAME	Column to sort by (see below)
sortorder	No	string	asc	Sort direction: asc or desc
filter	No	string	—	Filter tasks by exact name (case-insensitive)
status	No	string	—	Filter tasks by status: SUCCESS, FAILED, RETRYING, IN PROGRESS, or INACTIVE (case-insensitive)
enabled	No	string	—	Filter tasks by enabled state: true or false

Sort keys: TASK_NAME, SOURCE_TYPE, DATA_SOURCE, DATASET, TARGET_TABLE, STATUS, NEXT_ETA, ENABLED, SCHEDULE, CREATED, LAST_RUN.

Response: Array of task objects with fields: TASK_NAME, SOURCE_TYPE, DATA_SOURCE, DATASET, TARGET_TABLE, STATUS, STATUS_NOTE, NEXT_ETA, LAST_RUN, CREATED, ENABLED, SCHEDULE.

The DATA_SOURCE field contains the title of the data source. Falls back to the URL if no title is available. The STATUS field contains one of: SUCCESS, FAILED, RETRYING, IN PROGRESS, or INACTIVE. STATUS_NOTE provides context for the current status: while ingestion is running, it shows the current execution phase (e.g., "3/6 Retrieving"); when the task has failed, it contains the failure description including the phase where it occurred; when retrying, it shows the retry count and error (e.g., "Retry 1/2 — timeout"). NEXT_ETA shows the next scheduled run with a relative time suffix (e.g., "2026-04-08 06:00:00 (in 12 hours)"). TARGET_TABLE is the fully qualified Snowflake table name (e.g., MY_DB.SCHEMA.TABLE). ENABLED shows "Enabled" or "Disabled".

-- List first 5 tasks sorted by name
CALL SETUP.GDC_TASK('list', PARSE_JSON('{"page": 1, "length": 5, "sortkey": "TASK_NAME"}'));

-- List tasks sorted by most recent run (newest first)
CALL SETUP.GDC_TASK('list', PARSE_JSON('{"sortkey": "LAST_RUN", "sortorder": "desc"}'));

-- List only enabled tasks
CALL SETUP.GDC_TASK('list', PARSE_JSON('{"enabled": "true"}'));

-- List failed tasks
CALL SETUP.GDC_TASK('list', PARSE_JSON('{"status": "FAILED"}'));

-- Tabular output
CALL SETUP.GDC_TASK('list', NULL, 'table');

get

Returns a single task. Provide either the task name or the source identifiers.

Parameter	Required	Type	Description
name	Either name or all three source params	string	The task name (e.g., INGESTION_abc123def456)
url		string	The data source URL
type		string	Service type (e.g., WFS, WMS)
dataset		string	The dataset name within the service

Response: Same columns as list — a single task object. Returns null if the task does not exist.

-- Get by name
CALL SETUP.GDC_TASK('get', PARSE_JSON('{"name": "INGESTION_abc123def456"}'));

-- Get by source identifiers
CALL SETUP.GDC_TASK('get', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/bu_mtk_polygon",
  "type": "WFS",
  "dataset": "bu-core2d:Building"
}'));

runs

Returns the ingestion run history for a task, sorted newest first.

Parameter	Required	Type	Description
name	Yes	string	The task name

Response: Array of run objects with fields: NAME, START_TIME, END_TIME, STATUS, STATUS_NOTE, ERROR_MESSAGE, DURATION, TRIGGER, ROWS_LOADED. While a run is active, STATUS_NOTE shows the current execution phase (null for completed runs). ERROR_MESSAGE provides a failure description for failed runs (null for succeeded runs). DURATION is a formatted duration string (e.g., "2m 30s"). TRIGGER indicates how the run was started (e.g., "SCHEDULED", "MANUAL").

CALL SETUP.GDC_TASK('runs', PARSE_JSON('{"name": "INGESTION_abc123def456"}'));

table_info

Describes the ingested data table — its columns, row count, and a sample of rows.

Parameter	Required	Type	Description
name	Yes	string	The task name

Response: {table: string, column_count: integer, row_count: integer, columns: [{name, type}, ...], sample: [{...}, ...]}. The sample contains up to 10 rows with column values truncated to 200 characters.

Returns NOT_FOUND if the task or its target table does not exist.

CALL SETUP.GDC_TASK('table_info', PARSE_JSON('{"name": "INGESTION_abc123def456"}'));

metadata

Returns raster metadata for image-based source types.

Parameter	Required	Type	Description
name	Yes	string	The task name

Applicable source types: WMS, WMTS, WCS, OGC API Maps, OGC API Coverages. Returns empty metadata for other source types.

Response: {exists: boolean, table: string|null, metadata: {...}}. The metadata object contains source-specific fields such as coordinate reference system, pixel dimensions, and geographic extent.

CALL SETUP.GDC_TASK('metadata', PARSE_JSON('{"name": "INGESTION_abc123def456"}'));

stage_file_info

Returns information about the staged image file for a raster ingestion task.

Parameter	Required	Type	Description
name	Yes	string	The task name

Applicable source types: WMS, WMTS. Returns empty data for other source types.

Response: {exists: boolean, file_location: string|null, file_size: integer, file_name: string|null}.

CALL SETUP.GDC_TASK('stage_file_info', PARSE_JSON('{"name": "INGESTION_abc123def456"}'));

Discovery (GDC_DISCOVER)

Available to the APP_USER role. Requires External Access Integration. Browse and search geospatial data sources.

Note: Discovery and search calls retrieve data directly from external services and indexes. Response times depend on the external service. Only fields visible in the Connector's user interface are included in responses.

Actions

navigate

Browses an OGC service by URL. Use this to discover available datasets, list them, and inspect dataset details.

Parameter	Required	Type	Default	Description
url	Yes	string	—	The OGC service URL to browse
page	No	integer	1	Page number for paginated results (10 items per page)
node_id	No	string	—	Navigate to a specific dataset within the service
number	No	integer	—	Select a source by its row number (as shown in the overview)
item_number	No	integer	—	Drill into a specific item within the selected source
q	No	string	—	Filter results within the service (minimum 2 characters)

Note: Do not include authentication credentials (such as API keys or passwords) in the url parameter. URLs containing query parameters such as apikey, token, or password will be rejected. To access authenticated services, first save the connection using GDC_CONNECTION('upsert', ...) with the auth_method, auth_username, and auth_password parameters. See Connections (GDC_CONNECTION) for details.

Response: The navigate action may return data directly or a processing ticket, depending on whether the result is immediately available:

• Immediate response — Returns an object describing the current navigation level (see below).
• Deferred response — Returns {type: "ticket", ticket_id: "...", status: "processing"}. Use the status action to poll until the result is ready (typically 5–30 seconds). See the status action below.

When discovery data is returned (either immediately or after polling), the response structure depends on the navigation depth:

• Service overview ({url}) — {source: {...}, items: [...], source_count, service_health, ...} — the data source summary plus its first-level items.
• Service list ({url} returning multiple sources) — {sources: [...], source_count} — each entry is a separate data source to choose from with number.
• Items within the selected source ({url, number}) — {source, items, ...} — the chosen source with its items listed.
• Item detail ({url, number, item_number}) — either {source, ...} (for a catalog record, where the Connector drills through the record to the underlying data source) or {item, columns, ...} (for a dataset within a service, where the dataset is returned with its column schema). See Two item kinds below.

Each item in the items array carries a 1-based number field indicating its position in the list — use this value as item_number to drill into that item.

Table format — listing datasets or catalog records. In the 'table' format, calling navigate with only a url returns a single row describing the data source (title, type, url, dataset counts). It does not list the datasets or catalog records as rows. To get those as rows, add "number": 1 (or the row number of the source you want to expand when the URL returned multiple sources):

-- Table format: just the service summary (one row)
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://kart.hi.no/mareano/mareano_kjemi/perylen/ows?service=WFS"
}'), 'table');

-- Table format: list the service's datasets (or records) as rows
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://kart.hi.no/mareano/mareano_kjemi/perylen/ows?service=WFS",
  "number": 1
}'), 'table');

This is the standard pattern for listing datasets in table format, and the only way to see individual datasets/records as rows. In the 'json' format, the same {url} call already returns both the source summary and the items list together, so number is only needed when the URL exposes multiple sources and you want to select one.

Two item kinds. Items can be either nested data sources (when browsing a catalog such as CSW or OGC API Records, whose entries are themselves data sources) or datasets (when browsing a dataset-providing service such as WFS, WMS, WCS, WMTS, or OGC API Features). The fields present on each item reflect what the Connector's Discovery page shows for that kind:

Item kind	Typical services	Item fields	item_number result
Nested data source	CSW, OGC API Records	number, title, description, type, url, service_provider, data_source_count, dataset_count	The Connector drills through the record to the underlying data source and returns it as {source, ...} (or {sources: [...]} if the record points at multiple services) — typically a fully populated WFS/WMS service with its own url, ready to navigate further.
Dataset	WFS, WMS, WCS, WMTS, OGC API Features/Maps/Tiles/Coverages	number, name, title, description, type, source_type, url, bbox_wgs84, crs_epsg_code, crs_name, column_count, row_count, is_ingestible, ingestibility_note, column_schema_note	The selected dataset plus a columns list describing its column schema (name, type, description).

The response includes only the fields with meaningful values. Metadata fields such as service_health, search_active, total_matched, and search_capabilities are omitted when they have no content.

Dataset items include is_ingestible (true/false). When false, ingestibility_note provides a human-readable explanation (e.g., unsupported dataset type, invalid coordinate reference system, pixel count exceeding the limit, or a temporarily unreachable ingestion URL). Dataset items may also include column_schema_note when the column schema could not be resolved during discovery — an informational message; ingestion may still be possible.

Every discovery response includes a service_health object with the following fields:

Field	Description
status	HEALTHY, DEGRADED, DOWN, HALF_OPEN, or UNKNOWN
last_probe	ISO 8601 timestamp of the last health check (null if never checked)
response_time_ms	Response time of the most recent health check in milliseconds (null if never checked)
uptime_pct_7d	7-day uptime percentage (null if insufficient data)
uptime_pct_30d	30-day uptime percentage (null if insufficient data)
avg_response_ms_7d	7-day average response time in milliseconds (null if insufficient data)
availability	available, temporarily_unavailable, or permanently_unavailable (null if never checked)

-- Browse a WFS service
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple",
  "page": 1
}'));

-- Drill into a specific dataset
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple",
  "node_id": "au:AdministrativeBoundary"
}'));

-- Filter datasets within a service
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple",
  "q": "building"
}'));

-- Tabular output (one row per source — overview)
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple"
}'), 'table');

-- Tabular output with drill-down (show items within source 1)
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple",
  "number": 1
}'), 'table');

-- Drill into a specific dataset (item 3 within source 1) — shows column schema as rows
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://inspire-wfs.maanmittauslaitos.fi/inspire-wfs/simple",
  "number": 1,
  "item_number": 3
}'), 'table');

-- Drill into a catalog record (item 3 within a CSW catalog) — the Connector drills
-- through the record and returns the underlying data source (e.g. the WFS service)
-- as a single row, ready to navigate further.
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://www.geonorge.no/geonetwork/srv/nor/csw?service=CSW&request=GetCapabilities",
  "number": 1,
  "item_number": 3
}'), 'table');

status

Polls for the result of an asynchronous discovery request. Use this when navigate returns a ticket instead of immediate results.

Parameter	Required	Type	Description
ticket_id	Yes	string	The ticket ID returned by navigate or a previous status call

Response: The response includes a status field:

• processing — Discovery is still in progress. Wait 2–4 seconds and poll again with the same ticket_id.
• completed — Discovery data is ready and included in the response (same structure as an immediate navigate response).
• failed — Discovery failed. Check the error field for details.

-- Poll for discovery results
CALL SETUP.GDC_DISCOVER('status', PARSE_JSON('{"ticket_id": "abc-123-def-456"}'));

Empty responses

When navigate or status returns completed but the response contains no source, sources, or items, it means the Connector reached the URL but found no geospatial data sources. The response includes a service_health object indicating the health status of the service.

Common reasons for an empty response:

• Incorrect URL — The URL does not point to a valid OGC service. Verify the URL includes the correct service endpoint.
• Decommissioned service — The service was previously available but has been taken offline or moved to a different URL.
• Unsupported service version — The service uses an OGC protocol version that the Connector does not support.
• Network or access restrictions — The service is behind a firewall, requires authentication, or blocks external access.

In tabular output, an empty response shows a single row with STATUS and any available SERVICE_HEALTH_* columns.

Check the service_health.status field: HEALTHY or DEGRADED indicates the service was reachable but returned no datasets; UNKNOWN or DOWN suggests the service could not be probed or is unreachable.

search

Searches the Connector's dataset index by keyword. Returns matching datasets ranked by relevance.

Parameter	Required	Type	Default	Description
q	Yes	string	—	Search query (minimum 2 characters)
limit	No	integer	20	Maximum results to return
offset	No	integer	0	Number of results to skip (for pagination)
bbox	No	object	—	Geographic area filter: {"west": number, "south": number, "east": number, "north": number} in WGS 84 coordinates
filters	No	object	—	Filter results by country or service type: {"country": "FI", "type": "WFS"}. Both fields are optional.

Response: {results: [...], total: integer, query_info: {...}}. Each result includes a relevance score, service type, source name, and a discovered field showing when the dataset was indexed (e.g., "2 days ago"). The total field indicates the total number of matches (may exceed limit). The query_info object includes query (the original search query) and execution_time_ms (query duration in milliseconds). When the query mentions a geographic region, the Connector automatically uses spatial context to improve relevance.

-- Search for elevation data in Finland
CALL SETUP.GDC_DISCOVER('search', PARSE_JSON('{"q": "elevation data finland", "limit": 10}'));

-- Search with geographic area filter (Helsinki region)
CALL SETUP.GDC_DISCOVER('search', PARSE_JSON('{
  "q": "buildings",
  "bbox": {"west": 24.5, "south": 60.1, "east": 25.2, "north": 60.4},
  "limit": 10
}'));

-- Filter by country and service type
CALL SETUP.GDC_DISCOVER('search', PARSE_JSON('{
  "q": "geology",
  "filters": {"country": "FI", "type": "WFS"},
  "limit": 10
}'));

-- Tabular output (one row per result with TOTAL column)
CALL SETUP.GDC_DISCOVER('search', PARSE_JSON('{"q": "protected areas", "limit": 5}'), 'table');

URLs with query parameters

Some OGC service URLs contain & characters (e.g., ?service=CSW&request=GetCapabilities). These work without any special handling in Snowsight worksheets:

-- Works in Snowsight — no escaping needed
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://www.geonorge.no/geonetwork/srv/nor/csw?service=CSW&request=GetCapabilities",
  "page": 1
}'));

-- Tabular output — overview (1 service row)
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://www.geonorge.no/geonetwork/srv/nor/csw?service=CSW&request=GetCapabilities"
}'), 'table');

-- Tabular output — drill into source 1 (show items as rows)
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://www.geonorge.no/geonetwork/srv/nor/csw?service=CSW&request=GetCapabilities",
  "number": 1
}'), 'table');

-- Tabular output — drill into catalog record 3 within source 1. Because the
-- underlying service is a CSW catalog, the Connector drills through the record
-- and returns the underlying data source (e.g. a WFS service) as a single row.
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://www.geonorge.no/geonetwork/srv/nor/csw?service=CSW&request=GetCapabilities",
  "number": 1,
  "item_number": 3
}'), 'table');

If your SQL client interprets & as a variable substitution marker, use && to escape it:

-- Double && escapes the ampersand in clients that use & for variable substitution
CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{
  "url": "https://www.geonorge.no/geonetwork/srv/nor/csw?service=CSW&&request=GetCapabilities",
  "page": 1
}'));

Troubleshooting

SQL template rendering error with URLs

When using the Snowflake CLI (snow sql), URLs containing & characters may cause:

SQL template rendering error: 'request' is undefined

This is a client-side variable substitution feature in the Snowflake CLI. Disable it with --enable-templating NONE:

snow sql --enable-templating NONE --query "CALL SETUP.GDC_DISCOVER('navigate', PARSE_JSON('{\"url\": \"https://example.com/csw?service=CSW&request=GetCapabilities\"}'));"

This does not affect Snowsight worksheets or Cortex Analyst.

See also: AI Assistant Integration — use these procedures with Snowflake Cortex Code or Claude Code.