← Docs

API Reference

All 38 methods available through the Gold Lapel language wrappers.

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(dsn)

Start the GL proxy and return a connection string pointing at it

Parameters dsn: connection string
Returns Proxied connection string
Python 
import goldlapel

conn = goldlapel.start("postgresql://user:pass@localhost:5432/mydb")
# conn is a proxied connection string: postgresql://user:pass@localhost:7932/mydb

goldlapel.connect(dsn)

Connect to an already-running GL proxy

Parameters dsn: connection string (already proxied)
Returns Connection handle
Python 
conn = goldlapel.connect("postgresql://user:pass@localhost:7932/mydb")

goldlapel.stop(conn)

Stop the proxy process

Parameters conn: connection handle
Returns None
Python 
goldlapel.stop(conn)

goldlapel.wrap(conn)

Wrap a connection for L1 in-process caching

Parameters conn: connection handle
Returns Wrapped connection
Python 
wrapped = goldlapel.wrap(conn)
# Use wrapped for L1 in-process caching on top of L2 proxy cache

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

goldlapel.facets(conn, 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 conn, 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 = goldlapel.facets(conn, "articles", "category")
# [{"value": "technology", "count": 842}, {"value": "science", "count": 531}, ...]

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

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

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

Parameters conn, 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 = goldlapel.aggregate(conn, "orders", "total", "avg", group_by="region")
# [{"region": "us-east", "value": 89.50}, {"region": "eu-west", "value": 72.30}, ...]

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

goldlapel.create_search_config(conn, 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 conn, name: str, copy_from: str
Returns None
Python 
# Create a custom config based on English
goldlapel.create_search_config(conn, "my_english", copy_from="english")
# Then use it: goldlapel.search(conn, "articles", "body", "query", lang="my_english")

goldlapel.percolate_add(conn, 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 conn, name: str, query_id: str, query: str, lang: str, metadata: dict (optional)
Returns None
Python 
# Store a query for reverse matching
goldlapel.percolate_add(conn, "alerts", "breaking-news",
    "breaking news earthquake",
    metadata={"notify": "slack", "channel": "#alerts"})

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

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

Parameters conn, 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 = goldlapel.percolate(conn, "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}]

goldlapel.percolate_delete(conn, name, query_id)

Remove a stored query from a percolator index.

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

goldlapel.analyze(conn, 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 conn, text: str, lang: str
Returns List of {alias, description, token, dictionaries, dictionary, lexemes}
Python 
tokens = goldlapel.analyze(conn, "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"], ...}]

goldlapel.explain_score(conn, 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 conn, 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 = goldlapel.explain_score(conn, "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

goldlapel.publish(conn, channel, message)

Publish a message to a channel (backed by NOTIFY)

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

goldlapel.subscribe(conn, channel, callback)

Subscribe to a channel and invoke callback on each message

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

goldlapel.subscribe(conn, "orders", on_message)

Queues

goldlapel.enqueue(conn, queue, payload)

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

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

goldlapel.dequeue(conn, queue)

Pop the next job from a queue

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

Counters

goldlapel.incr(conn, table, key, amount=1)

Increment a counter atomically

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

goldlapel.get_counter(conn, table, key)

Get the current value of a counter

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

Hash Maps

goldlapel.hset(conn, table, key, field, value)

Set a field in a hash map (upsert)

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

goldlapel.hget(conn, table, key, field)

Get a single field from a hash map

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

goldlapel.hgetall(conn, table, key)

Get all fields from a hash map

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

goldlapel.hdel(conn, table, key, field)

Delete a field from a hash map

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

Sorted Sets

goldlapel.zadd(conn, table, member, score)

Add a member with a score to a sorted set

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

goldlapel.zincrby(conn, table, member, amount=1)

Increment a member's score

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

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

Get members by rank range

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

goldlapel.zrank(conn, table, member, desc=True)

Get a member's rank

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

goldlapel.zscore(conn, table, member)

Get a member's score

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

goldlapel.zrem(conn, table, member)

Remove a member from a sorted set

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

Geospatial

Requires the PostGIS extension.

goldlapel.geoadd(conn, table, name_col, geom_col, name, lon, lat)

Add a named location with longitude/latitude

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

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

Find locations within a radius (meters)

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

goldlapel.geodist(conn, table, geom_col, name_col, a, b)

Distance between two named locations

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

Cardinality

goldlapel.count_distinct(conn, table, column)

Exact count of distinct values in a column

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

Scripting

Requires the pllua extension.

goldlapel.script(conn, lua_code, *args)

Execute a Lua script on PostgreSQL (requires pllua extension)

Parameters conn, lua_code: str, *args: variadic
Returns Script result
Python 
result = goldlapel.script(conn, """
    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

goldlapel.stream_add(conn, stream, payload)

Append a message to a stream

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

goldlapel.stream_create_group(conn, stream, group)

Create a consumer group for a stream

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

goldlapel.stream_read(conn, stream, group, consumer, count=1)

Read unacknowledged messages as a consumer

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

goldlapel.stream_ack(conn, stream, group, message_id)

Acknowledge a message (remove from pending)

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

goldlapel.stream_claim(conn, stream, group, consumer, min_idle_ms=60000)

Reclaim messages idle longer than min_idle_ms

Parameters conn, stream: str, group: str, consumer: str, min_idle_ms: int
Returns List of reclaimed messages
Python 
reclaimed = goldlapel.stream_claim(conn, "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_casegoldlapel.stream_read()
JavaScriptcamelCasegoldlapel.streamRead()
Rubysnake_caseGoldlapel.stream_read()
JavacamelCaseGoldlapel.streamRead()
GoPascalCasegoldlapel.StreamRead()
.NETPascalCaseGoldlapel.StreamRead()
PHPsnake_caseGoldlapel::stream_read()

Parameters and return types are identical across languages. Connection handles returned by start() are opaque strings (connection URLs) in every wrapper.