GridX Function Reference (BNG)

Complete reference for all GridX British National Grid (BNG) functions with detailed descriptions, parameters, return values, and examples.

Overview

GridX provides functions for working with the British National Grid coordinate system, a specialized grid system used in Great Britain for spatial indexing and location-based services.

Function Count: 23 functions organized into 7 categories:

Conversion Functions (2): Convert cells to geometries
Core Functions (4): Basic cell operations
Cell Operations (2): Intersection and union
Coordinate Conversion (2): Point/coordinate to cell
K-Ring Functions (4): Neighboring cells
Tessellation Functions (2): Fill geometries with cells
Aggregator Functions (2): Aggregate operations
Generator Functions (5): Explode arrays into rows

SQL examples

Examples on this page use SQL (and Python where shown); in SQL, GridX functions are prefixed with gbx_ (e.g. gbx_bng_aswkb, gbx_bng_cellarea). For more language-specific tips, see the Python, Scala, and SQL API pages.

Common setup

Run this once before the examples below. It registers GridX (BNG) so you can use bng_* in Python and gbx_bng_* in SQL.

from databricks.labs.gbx.gridx.bng import functions as bx
bx.register(spark)

Example output
GridX (BNG) registered. You can now use bng_* functions in Python and gbx_bng_* in SQL.

Conversion Functions

Functions to convert BNG cell IDs to standard geometry formats.

bng_aswkb

Convert a BNG cell ID to Well-Known Binary (WKB) format.

Signature: bng_aswkb(cellId: Column): Column

Parameters:

cellId - BNG cell reference string

Returns:

Binary WKB geometry representation

SQL:

SELECT gbx_bng_aswkb('TQ3080') as wkb_geom;

Example output
+--------------------+
|wkb_geom            |
+--------------------+
|[BINARY]            |
+--------------------+

bng_aswkt

Convert a BNG cell ID to Well-Known Text (WKT) format.

Signature: bng_aswkt(cellId: Column): Column

Parameters:

cellId - BNG cell reference string

Returns:

String WKT geometry representation

SQL:

SELECT gbx_bng_aswkt('TQ3080') as wkt_geom;

Example output
+------------------------------------------+
|wkt_geom                                  |
+------------------------------------------+
|POLYGON ((...))                           |
+------------------------------------------+

Core Functions

Fundamental operations on BNG cells.

bng_cellarea

Calculate the area of a BNG grid cell.

Signature: bng_cellarea(cellId: Column): Column

Parameters:

cellId - BNG cell reference

Returns:

Double representing the cell area in square kilometres

SQL:

SELECT 
    'TQ3080' as cell,
    gbx_bng_cellarea('TQ3080') as area_km2
FROM locations;

Example output
+------+----------+
|cell  |area_km2  |
+------+----------+
|TQ3080|1.0       |
+------+----------+

bng_centroid

Get the centroid (center point) of a BNG cell.

Signature: bng_centroid(cellId: Column): Column

Parameters:

cellId - BNG cell reference

Returns:

Point geometry at cell center

SQL:

SELECT gbx_bng_centroid('TQ3080') as centroid;

Example output
+--------------------+
|centroid            |
+--------------------+
|POINT (...)         |
+--------------------+

bng_distance

Calculate distance between two BNG cells.

Signature: bng_distance(cell1: Column, cell2: Column): Column

Parameters:

cell1 - First BNG cell reference
cell2 - Second BNG cell reference

Returns:

Double representing distance in meters

SQL:

SELECT 
            gbx_bng_distance('TQ3080', 'TQ3081') as distance_m

Example output
+-----------+
|distance_m |
+-----------+
|1000.0     |
+-----------+

bng_euclideandistance

Calculate Euclidean distance between two BNG cells.

Signature: bng_euclideandistance(cell1: Column, cell2: Column): Column

Parameters:

cell1 - First BNG cell reference
cell2 - Second BNG cell reference

Returns:

Double representing Euclidean distance in meters

SQL:

SELECT 
            gbx_bng_euclideandistance('TQ3080', 'TQ3081') as euclidean_distance_m

Example output
+----------------+
|euclidean_dist_m|
+----------------+
|1414.21         |
+----------------+

Cell Operations

Operations combining multiple cells.

bng_cellintersection

Get the intersection of two BNG cells.

Signature: bng_cellintersection(cell1: Column, cell2: Column): Column

Parameters:

cell1 - First BNG cell reference
cell2 - Second BNG cell reference

Returns:

BNG cell ID representing the intersection

SQL:

SELECT 
            gbx_bng_cellintersection('TQ3080', 'TQ3081') as intersection_cell

Example output
+------------------+
|intersection_cell |
+------------------+
|TQ3080            |
+------------------+

bng_cellunion

Get the union of two BNG cells.

Signature: bng_cellunion(cell1: Column, cell2: Column): Column

Parameters:

cell1 - First BNG cell reference
cell2 - Second BNG cell reference

Returns:

BNG cell ID representing the union

SQL:

SELECT 
            gbx_bng_cellunion('TQ3080', 'TQ3081') as union_cell

Example output
+-----------+
|union_cells|
+-----------+
|TQ3079     |
+-----------+

Coordinate Conversion Functions

Convert coordinates or geometries to BNG cells.

bng_eastnorthasbng

Convert easting/northing coordinates to a BNG cell reference.

Signature: bng_eastnorthasbng(easting: Column, northing: Column, resolution: Column): Column

Parameters:

easting - Easting coordinate value
northing - Northing coordinate value
resolution - BNG resolution: integer index (1–6 or negative for quadrant) or string (e.g. '1km', '100m'). See resolutionMap in BNG.

Returns:

String BNG cell reference

SQL:

-- Convert OS Grid Reference coordinates (easting, northing); resolution '1km' or integer 3
SELECT gbx_bng_eastnorthasbng(530000, 180000, '1km') as bng_cell;

Example output
+----------+
|bng_cell  |
+----------+
|TQ3080    |
+----------+

bng_pointascell

Convert a point geometry to a BNG grid cell. The point must be supplied as WKT or WKB (GeoBrix does not accept native Databricks geometry types).

Signature: bng_pointascell(point: Column, resolution: Column): Column

Parameters:

point - Point geometry as WKT (string) or WKB (binary). For example, WKT: 'POINT(-0.1278 51.5074)'. Do not use st_point() or other DBR native geometry functions—they return a type GeoBrix does not accept.
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')

Returns:

String BNG cell reference

Python (point as WKT column):

from databricks.labs.gbx.gridx.bng import functions as bx
from pyspark.sql.functions import lit
bx.register(spark)
df = spark.range(1).select(
    bx.bng_pointascell(lit("POINT(530000 180000)"), lit("1km")).alias("bng_cell")
)
df.show()

Scala: Pass a WKT or WKB column and BNG resolution (e.g. bx.bng_pointascell(lit("POINT(530000 180000)"), lit("1km")) for BNG coords, or lit(3) for 1 km index). Do not use st_point().

SQL:

-- Point in BNG coordinates (eastings, northings); resolution '1km' for 1 km cell
SELECT gbx_bng_pointascell('POINT(530000 180000)', '1km') as london_cell;

Example output
+------------+
|london_cell |
+------------+
|TQ3080      |
+------------+

K-Ring Functions

Generate neighboring cells using k-ring patterns.

bng_kring

Generate a k-ring of cells around a center cell (filled disk).

Signature: bng_kring(cellId: Column, k: Column): Column

Parameters:

cellId - BNG cell reference for center
k - Integer ring distance (0 = just center, 1 = center + neighbors, etc.)

Returns:

Array of BNG cell references in the k-ring

SQL:

-- Get all cells within 2 rings of center
SELECT 
    cell_id,
    gbx_bng_kring(cell_id, 2) as nearby_cells
FROM locations;

Example output
+------+--------------------------------+
|cell_id|nearby_cells                   |
+------+--------------------------------+
|TQ3080|[TQ3079, TQ3081, TQ2979, ...]   |
+------+--------------------------------+

bng_kloop

Generate a k-loop of cells around a center cell (hollow ring).

Signature: bng_kloop(cellId: Column, k: Column): Column

Parameters:

cellId - BNG cell reference for center
k - Integer ring distance

Returns:

Array of BNG cell references at exactly distance k

SQL:

SELECT 
            'TQ3080' as center,
            gbx_bng_kloop('TQ3080', 2) as kloop_cells

Example output
+------+-------------------------------+
|cell_id|kloop_cells                   |
+------+-------------------------------+
|TQ3080|[TQ3079, TQ3081, TQ2979, ...]  |
+------+-------------------------------+

bng_geomkring

Generate a k-ring of cells around a geometry at specified resolution.

Signature: bng_geomkring(geom: Column, resolution: Column, k: Column): Column

Parameters:

geom - Input geometry (any type)
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')
k - Integer ring distance

Returns:

Array of BNG cell references

SQL:

SELECT gbx_bng_geomkring(
            st_geomfromtext('POLYGON((-0.1 51.5, -0.1 51.6, 0.0 51.6, 0.0 51.5, -0.1 51.5))'),
            3, 1
        ) as kring_cells

Example output
+------+--------------------------------+
|cell_id|geom_kring                     |
+------+--------------------------------+
|TQ3080|[POLYGON (...), POLYGON (...)]  |
+------+--------------------------------+

bng_geomkloop

Generate a k-loop of cells around a geometry at specified resolution.

Signature: bng_geomkloop(geom: Column, resolution: Column, k: Column): Column

Parameters:

geom - Input geometry (any type)
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')
k - Integer ring distance

Returns:

Array of BNG cell references at exactly distance k

SQL:

SELECT gbx_bng_geomkloop(
            st_geomfromtext('POLYGON((-0.1 51.5, -0.1 51.6, 0.0 51.6, 0.0 51.5, -0.1 51.5))'),
            3, 1
        ) as kloop_cells

Example output
+------+--------------------------------+
|cell_id|geom_kloop                     |
+------+--------------------------------+
|TQ3080|[POLYGON (...), ...]            |
+------+--------------------------------+

Tessellation Functions

Fill geometries with grid cells.

bng_polyfill

Fill a geometry with BNG cells at specified resolution.

Signature: bng_polyfill(geometry: Column, resolution: Column): Column

Parameters:

geometry - Input geometry to fill
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')

Returns:

Array of BNG cell IDs covering the geometry

SQL:

-- Fill a polygon with 1km cells
SELECT 
    region_name,
    gbx_bng_polyfill(boundary, 3) as cells
FROM regions;

Example output
+------------+-------------------+
|region_name |cells              |
+------------+-------------------+
|London      |[TQ3079, TQ3080,..]|
+------------+-------------------+

bng_tessellate

Tessellate a geometry into BNG cells with their geometries.

Signature: bng_tessellate(geometry: Column, resolution: Column): Column

Parameters:

geometry - Input geometry to tessellate
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')

Returns:

Array of structs containing cell ID and geometry

SQL:

SELECT gbx_bng_tessellate(
            st_geomfromtext('POLYGON((-0.1 51.5, -0.1 51.6, 0.0 51.6, 0.0 51.5, -0.1 51.5))'),
            3
        ) as tessellation

Example output
+----------------------------------------+
|cell_info                               |
+----------------------------------------+
|{cellId=TQ3080, wkb=[BINARY], ...}      |
+----------------------------------------+

Aggregator Functions

Aggregate multiple cells into a single result.

bng_cellintersection_agg

Aggregate intersection of multiple BNG cells.

Signature: bng_cellintersection_agg(cellId: Column): Column

Parameters:

cellId - BNG cell reference column to aggregate

Returns:

BNG cell ID representing common intersection

SQL:

-- Find common cell across groups
SELECT 
    group_id,
    gbx_bng_cellintersection_agg(cell_id) as common_cell
FROM observations
GROUP BY group_id;

Example output
+--------+------------+
|group_id|common_cell |
+--------+------------+
|1       |TQ3080      |
+--------+------------+

bng_cellunion_agg

Aggregate union of multiple BNG cells.

Signature: bng_cellunion_agg(cellId: Column): Column

Parameters:

cellId - BNG cell reference column to aggregate

Returns:

BNG cell ID representing bounding union

SQL:

SELECT 
    region,
    gbx_bng_cellunion_agg(cell_id) as bounding_cell
FROM observations
GROUP BY region;

Example output
+------+--------------+
|region|bounding_cell |
+------+--------------+
|South |TQ3080        |
+------+--------------+

Generator Functions

Explode array results into individual rows.

bng_kringexplode

Explode k-ring cells into separate rows.

Signature: bng_kringexplode(cellId: Column, k: Column): Column

Parameters:

cellId - BNG cell reference for center
k - Integer ring distance

Returns:

Exploded rows, one per cell in k-ring

SQL:

SELECT 
            'TQ3080' as center_cell,
            explode(gbx_bng_kring('TQ3080', 2)) as nearby_cell

Example output
+------+---------+
|cell_id|neighbor|
+------+---------+
|TQ3080|TQ3079   |
|TQ3080|TQ3081   |
+------+---------+

bng_kloopexplode

Explode k-loop cells into separate rows.

Signature: bng_kloopexplode(cellId: Column, k: Column): Column

Parameters:

cellId - BNG cell reference for center
k - Integer ring distance

Returns:

Exploded rows, one per cell in k-loop

SQL:

SELECT 
            'TQ3080' as center_cell,
            explode(gbx_bng_kloop('TQ3080', 2)) as ring_cell

Example output
+------+---------+
|cell_id|neighbor|
+------+---------+
|TQ3080|TQ3079   |
|TQ3080|TQ3081   |
+------+---------+

bng_geomkringexplode

Explode geometry k-ring cells into separate rows.

Signature: bng_geomkringexplode(geom: Column, resolution: Column, k: Column): Column

Parameters:

geom - Input geometry
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')
k - Integer ring distance

Returns:

Exploded rows, one per cell

SQL:

SELECT explode(gbx_bng_geomkring(
            st_geomfromtext('POINT(-0.1278 51.5074)'), 3, 1
        )) as cell

Example output
+------+--------+
|cell_id|geom   |
+------+--------+
|TQ3080|POLYGON |
+------+--------+

bng_geomkloopexplode

Explode geometry k-loop cells into separate rows.

Signature: bng_geomkloopexplode(geom: Column, resolution: Column, k: Column): Column

Parameters:

geom - Input geometry
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')
k - Integer ring distance

Returns:

Exploded rows, one per cell at distance k

SQL:

SELECT explode(gbx_bng_geomkloop(
            st_geomfromtext('POINT(-0.1278 51.5074)'), 3, 1
        )) as cell

Example output
+------+--------+
|cell_id|geom   |
+------+--------+
|TQ3080|POLYGON |
+------+--------+

bng_tessellateexplode

Explode tessellated cells into separate rows.

Signature: bng_tessellateexplode(geometry: Column, resolution: Column): Column

Parameters:

geometry - Input geometry to tessellate
resolution - BNG resolution: integer index (e.g. 3 for 1 km) or string (e.g. '1km', '100m')

Returns:

Exploded rows with cell ID and geometry for each cell

SQL:

SELECT explode(gbx_bng_tessellate(
            st_geomfromtext('POLYGON((-0.1 51.5, -0.1 51.6, 0.0 51.6, 0.0 51.5, -0.1 51.5))'),
            3
        )) as cell_info

Example output
+----------------------------------------+
|cell_info                               |
+----------------------------------------+
|{cellId=TQ3080, wkb=[BINARY], ...}      |
+----------------------------------------+

BNG Reference Format

Standard Format

BNG references follow: [Letters][Eastings][Northings]

Common Resolutions

Resolution	Grid Size	Example	Use Case
100000m	100km × 100km	TQ	Regional
10000m	10km × 10km	TQ38	District
1000m	1km × 1km	TQ3080	Local area
100m	100m × 100m	TQ308808	Neighborhood
10m	10m × 10m	TQ30808080	Building
1m	1m × 1m	TQ3080080800	Precise location

Major Grid Squares

Major 100km grid squares in Great Britain:

TQ - London area
SU - South Hampshire
NT - Edinburgh area
SD - Lake District
ST - Bristol area

Performance Tips

1. Use Appropriate Resolution

Choose resolution based on analysis needs:

Coarse (10km) for regional analysis
Medium (1km) for local patterns
Fine (100m) for detailed studies

2. Leverage Aggregators

Use aggregator functions for efficient grouping:

SELECT 
    region,
    gbx_bng_cellunion_agg(cell_id) as bounding_cell
FROM observations
GROUP BY region;

Example output
+------+--------------+
|region|bounding_cell |
+------+--------------+
|South |TQ3080        |
+------+--------------+

3. Use Generators for Expansion

Generator functions (e.g. bng_kringexplode, bng_kloopexplode) are more efficient than using explode on array results. See the generator examples above.

Overview​

Common setup​

Conversion Functions​

bng_aswkb​

bng_aswkt​

Core Functions​

bng_cellarea​

bng_centroid​

bng_distance​

bng_euclideandistance​

Cell Operations​

bng_cellintersection​

bng_cellunion​

Coordinate Conversion Functions​

bng_eastnorthasbng​

bng_pointascell​

K-Ring Functions​

bng_kring​

bng_kloop​

bng_geomkring​

bng_geomkloop​

Tessellation Functions​

bng_polyfill​

bng_tessellate​

Aggregator Functions​

bng_cellintersection_agg​

bng_cellunion_agg​

Generator Functions​

bng_kringexplode​

bng_kloopexplode​

bng_geomkringexplode​

bng_geomkloopexplode​

bng_tessellateexplode​

BNG Reference Format​

Standard Format​

Common Resolutions​

Major Grid Squares​

Performance Tips​

1. Use Appropriate Resolution​

2. Leverage Aggregators​

3. Use Generators for Expansion​

Next Steps​

Overview

Common setup

Conversion Functions

bng_aswkb

bng_aswkt

Core Functions

bng_cellarea

bng_centroid

bng_distance

bng_euclideandistance

Cell Operations

bng_cellintersection

bng_cellunion

Coordinate Conversion Functions

bng_eastnorthasbng

bng_pointascell

K-Ring Functions

bng_kring

bng_kloop

bng_geomkring

bng_geomkloop

Tessellation Functions

bng_polyfill

bng_tessellate

Aggregator Functions

bng_cellintersection_agg

bng_cellunion_agg

Generator Functions

bng_kringexplode

bng_kloopexplode

bng_geomkringexplode

bng_geomkloopexplode

bng_tessellateexplode

BNG Reference Format

Standard Format

Common Resolutions

Major Grid Squares

Performance Tips

1. Use Appropriate Resolution

2. Leverage Aggregators

3. Use Generators for Expansion

Next Steps