← Docs

API Reference

Every method available through the Gold Lapel language wrappers.

In v0.2 the wrappers are driver-agnostic: goldlapel.start(url) is a factory that spawns the proxy and returns a GoldLapel instance. Bring your own Postgres driver and point it at gl.url. Method names follow each language's conventions: Python/Ruby/PHP use snake_case, JavaScript/Java use camelCase, Go/.NET use PascalCase. Signatures below use Python as the primary format.

Core

goldlapel.start(url, **opts)

Factory that spawns the proxy and returns a GoldLapel instance. Each call returns a fresh instance — use different ports to run several side by side.

Parameters url: str, config: dict, port: int, log_level: str, extra_args: list, no_connect: bool
Returns GoldLapel instance
Python 
import goldlapel

gl = goldlapel.start("postgresql://user:pass@localhost:5432/mydb")
# gl.url → "postgresql://user:pass@localhost:7932/mydb"
# Bring your own driver and point it at gl.url

gl.url

Proxy connection string — pass this to any Postgres driver.

Parameters (property)
Returns Proxy URL (str)
Python 
gl.url
# "postgresql://user:pass@localhost:7932/mydb"

gl.dashboard_url

Dashboard URL, or None when the dashboard is disabled or the proxy is not running.

Parameters (property)
Returns Dashboard URL (str) or None
Python 
gl.dashboard_url
# "http://127.0.0.1:7933"  (or None if disabled / not running)

gl.stop()

Stop the proxy process. Idempotent, runs automatically on process exit.

Parameters (none)
Returns None
Python 
gl.stop()

Backed by PostgreSQL full-text search (tsvector/tsquery). No extensions required.

gl.facets(table, column, limit=50, query=None, query_column=None, lang="english")

Value counts for a column, optionally filtered by a full-text query. Like Elasticsearch terms aggregation.

Parameters table: str, column: str, limit: int, query: str (optional), query_column: str (optional), lang: str
Returns List of {value, count}
Python 
# Top categories across all articles
results = gl.facets("articles", "category")
# [{"value": "technology", "count": 842}, {"value": "science", "count": 531}, ...]

# Top categories filtered by a search query
results = gl.facets("articles", "category", query="machine learning", query_column="body")

gl.aggregate(table, column, func, group_by=None, limit=50)

Compute an aggregate over a column, optionally grouped. Like Elasticsearch metric aggregations.

Parameters table: str, column: str, func: str (count/sum/avg/min/max), group_by: str (optional), limit: int
Returns List of {group_by, value} or [{value}]
Python 
# Average order total grouped by region
results = gl.aggregate("orders", "total", "avg", group_by="region")
# [{"region": "us-east", "value": 89.50}, {"region": "eu-west", "value": 72.30}, ...]

# Global sum
results = gl.aggregate("orders", "total", "sum")
# [{"value": 1847293.50}]

gl.create_search_config(name, copy_from="english")

Create a custom text search configuration by copying an existing one. Pass the config name as the lang parameter to search methods.

Parameters name: str, copy_from: str
Returns None
Python 
# Create a custom config based on English
gl.create_search_config("my_english", copy_from="english")
# Then use it: gl.search("articles", "body", "query", lang="my_english")

gl.percolate_add(name, query_id, query, lang="english", metadata=None)

Register a named query for reverse matching. Like Elasticsearch percolator — store queries, match documents against them later.

Parameters name: str, query_id: str, query: str, lang: str, metadata: dict (optional)
Returns None
Python 
# Store a query for reverse matching
gl.percolate_add("alerts", "breaking-news",
    "breaking news earthquake",
    metadata={"notify": "slack", "channel": "#alerts"})

gl.percolate(name, text, lang="english", limit=50)

Match a document against stored queries. Returns matching queries ranked by relevance score.

Parameters name: str, text: str, lang: str, limit: int
Returns List of {query_id, query_text, metadata, _score}
Python 
# Match a document against stored queries
matches = gl.percolate("alerts",
    "A 6.2 magnitude earthquake struck the coast, breaking news from the USGS.")
# [{"query_id": "breaking-news", "query_text": "breaking news earthquake",
#   "metadata": {"notify": "slack", "channel": "#alerts"}, "_score": 0.12}]

gl.percolate_delete(name, query_id)

Remove a stored query from a percolator index.

Parameters name: str, query_id: str
Returns Boolean (True if deleted)
Python 
gl.percolate_delete("alerts", "breaking-news")
# True

gl.analyze(text, lang="english")

Show how text is tokenized through the full-text search pipeline. Like Elasticsearch _analyze API — useful for debugging why searches match or miss.

Parameters text: str, lang: str
Returns List of {alias, description, token, dictionaries, dictionary, lexemes}
Python 
tokens = gl.analyze("The quick brown foxes jumped")
# [{"alias": "english_stem", "token": "quick", "lexemes": ["quick"], ...},
#  {"alias": "english_stem", "token": "brown", "lexemes": ["brown"], ...},
#  {"alias": "english_stem", "token": "foxes", "lexemes": ["fox"], ...},
#  {"alias": "english_stem", "token": "jumped", "lexemes": ["jump"], ...}]

gl.explain_score(table, column, query, id_column, id_value, lang="english")

Explain why a specific document scored what it did for a query. Like Elasticsearch _explain API — shows tokenization, match status, score, and highlighted headline.

Parameters table: str, column: str, query: str, id_column: str, id_value: any, lang: str
Returns {document_text, document_tokens, query_tokens, matches, score, headline}
Python 
result = gl.explain_score("articles", "body",
    "machine learning", id_column="id", id_value=42)
# {"document_text": "An introduction to machine learning...",
#  "document_tokens": "'introduct':2 'learn':5 'machin':4 ...",
#  "query_tokens": "'learn' & 'machin'",
#  "matches": True,
#  "score": 0.0607927,
#  "headline": "An introduction to **machine** **learning**..."}

Pub/Sub

gl.publish(channel, message)

Publish a message to a channel (backed by NOTIFY)

Parameters channel: str, message: str
Returns None
Python 
gl.publish("orders", '{"id": 42, "status": "shipped"}')

gl.subscribe(channel, callback)

Subscribe to a channel and invoke callback on each message

Parameters channel: str, callback: fn(str)
Returns Subscription handle
Python 
def on_message(msg):
    print(f"received: {msg}")

gl.subscribe("orders", on_message)

Queues

gl.enqueue(queue, payload)

Add a job to a durable queue (backed by SKIP LOCKED)

Parameters queue: str, payload: str
Returns None
Python 
gl.enqueue("emails", '{"to": "user@example.com", "template": "welcome"}')

gl.dequeue(queue)

Pop the next job from a queue

Parameters queue: str
Returns Payload string or None
Python 
job = gl.dequeue("emails")
# {"to": "user@example.com", "template": "welcome"}

Counters

gl.incr(table, key, amount=1)

Increment a counter atomically

Parameters table: str, key: str, amount: int (default 1)
Returns New value
Python 
gl.incr("page_views", "/home", 1)

gl.get_counter(table, key)

Get the current value of a counter

Parameters table: str, key: str
Returns Current value (int)
Python 
count = gl.get_counter("page_views", "/home")
# 1847

Hash Maps

gl.hset(table, key, field, value)

Set a field in a hash map (upsert)

Parameters table: str, key: str, field: str, value: str
Returns None
Python 
gl.hset("sessions", "sess_abc", "user_id", "42")

gl.hget(table, key, field)

Get a single field from a hash map

Parameters table: str, key: str, field: str
Returns Value string or None
Python 
val = gl.hget("sessions", "sess_abc", "user_id")
# "42"

gl.hgetall(table, key)

Get all fields from a hash map

Parameters table: str, key: str
Returns Dict of field/value pairs
Python 
fields = gl.hgetall("sessions", "sess_abc")
# {"user_id": "42", "role": "admin"}

gl.hdel(table, key, field)

Delete a field from a hash map

Parameters table: str, key: str, field: str
Returns None
Python 
gl.hdel("sessions", "sess_abc", "user_id")

Sorted Sets

gl.zadd(table, member, score)

Add a member with a score to a sorted set

Parameters table: str, member: str, score: float
Returns None
Python 
gl.zadd("leaderboard", "player_1", 2500)

gl.zincrby(table, member, amount=1)

Increment a member's score

Parameters table: str, member: str, amount: float (default 1)
Returns New score
Python 
gl.zincrby("leaderboard", "player_1", 10)

gl.zrange(table, start=0, stop=10, desc=True)

Get members by rank range

Parameters table: str, start: int, stop: int, desc: bool
Returns List of {member, score}
Python 
top_ten = gl.zrange("leaderboard", 0, 10, desc=True)
# [{"member": "player_1", "score": 2510}, ...]

gl.zrank(table, member, desc=True)

Get a member's rank

Parameters table: str, member: str, desc: bool
Returns Rank (int) or None
Python 
rank = gl.zrank("leaderboard", "player_1", desc=True)
# 0  (first place)

gl.zscore(table, member)

Get a member's score

Parameters table: str, member: str
Returns Score (float) or None
Python 
score = gl.zscore("leaderboard", "player_1")
# 2510

gl.zrem(table, member)

Remove a member from a sorted set

Parameters table: str, member: str
Returns None
Python 
gl.zrem("leaderboard", "player_1")

Geospatial

Requires the PostGIS extension.

gl.geoadd(table, name_col, geom_col, name, lon, lat)

Add a named location with longitude/latitude

Parameters table: str, name_col: str, geom_col: str, name: str, lon: float, lat: float
Returns None
Python 
gl.geoadd("locations", "name", "geom", "HQ", -73.985, 40.748)

gl.georadius(table, geom_col, lon, lat, radius_m, limit=50)

Find locations within a radius (meters)

Parameters table: str, geom_col: str, lon: float, lat: float, radius_m: float, limit: int
Returns List of {name, dist_m}
Python 
nearby = gl.georadius("locations", "geom", -73.985, 40.748, 5000, limit=20)
# [{"name": "HQ", "dist_m": 0.0}, {"name": "Office B", "dist_m": 1234.5}]

gl.geodist(table, geom_col, name_col, a, b)

Distance between two named locations

Parameters table: str, geom_col: str, name_col: str, a: str, b: str
Returns Distance in meters (float)
Python 
meters = gl.geodist("locations", "geom", "name", "HQ", "Office B")
# 1234.5

Cardinality

gl.count_distinct(table, column)

Exact count of distinct values in a column

Parameters table: str, column: str
Returns Count (int)
Python 
n = gl.count_distinct("orders", "customer_id")
# 8491

Scripting

Requires the pllua extension.

gl.script(lua_code, *args)

Execute a Lua script on PostgreSQL (requires pllua extension)

Parameters lua_code: str, *args: variadic
Returns Script result
Python 
result = gl.script("""
    local key, amount = args[1], tonumber(args[2])
    local current = gl.query("SELECT balance FROM accounts WHERE id = $1", key)
    gl.exec("UPDATE accounts SET balance = balance + $1 WHERE id = $2", amount, key)
    return current[1].balance + amount
""", "acct_123", "50")

Streams

gl.stream_add(stream, payload)

Append a message to a stream

Parameters stream: str, payload: str
Returns Message ID (str)
Python 
msg_id = gl.stream_add("events", '{"type": "signup", "user": 42}')
# "1712000000000-0"

gl.stream_create_group(stream, group)

Create a consumer group for a stream

Parameters stream: str, group: str
Returns None
Python 
gl.stream_create_group("events", "email_workers")

gl.stream_read(stream, group, consumer, count=1)

Read unacknowledged messages as a consumer

Parameters stream: str, group: str, consumer: str, count: int
Returns List of {id, payload}
Python 
messages = gl.stream_read("events", "email_workers", "worker_1", count=5)
# [{"id": "1712000000000-0", "payload": {"type": "signup", "user": 42}}]

gl.stream_ack(stream, group, message_id)

Acknowledge a message (remove from pending)

Parameters stream: str, group: str, message_id: str
Returns None
Python 
gl.stream_ack("events", "email_workers", "1712000000000-0")

gl.stream_claim(stream, group, consumer, min_idle_ms=60000)

Reclaim messages idle longer than min_idle_ms

Parameters stream: str, group: str, consumer: str, min_idle_ms: int
Returns List of reclaimed messages
Python 
reclaimed = gl.stream_claim("events", "email_workers", "worker_2", min_idle_ms=60000)
# Messages idle for 60s+ are reassigned to worker_2

Language Variants

Every method is available in all seven language wrappers. The naming convention adapts to each language:

LanguageConventionExample
Pythonsnake_casegl.stream_read()
JavaScriptcamelCasegl.streamRead()
Rubysnake_casegl.stream_read()
JavacamelCasegl.streamRead()
GoPascalCasegl.StreamRead()
.NETPascalCasegl.StreamRead()
PHPsnake_case$gl->stream_read()

Parameters and return types are identical across languages. Each call to goldlapel.start(url) returns a fresh GoldLapel instance — run several on different ports to target multiple databases, or share a single instance across your app.