jasei/postgres-hll

PostgreSQL with HLL Extension 镜像文档

镜像概述

本镜像基于PostgreSQL数据库，预集成了https://github.com/citusdata/postgresql-hll%E6%89%A9%E5%B1%95%E3%80%82postgres-hll%E6%98%AF%E4%B8%80%E4%B8%AA%E5%BC%80%E6%BA%90%E7%9A%84PostgreSQL%E6%89%A9%E5%B1%95%EF%BC%8C%E5%AE%9E%E7%8E%B0%E4%BA%86HyperLogLog%E7%AE%97%E6%B3%95%EF%BC%8C%E7%94%A8%E4%BA%8E%E9%AB%98%E6%95%88%E8%AE%A1%E7%AE%97%E5%92%8C%E5%AD%98%E5%82%A8%E5%A4%A7%E5%9E%8B%E6%95%B0%E6%8D%AE%E9%9B%86%E7%9A%84%E5%9F%BA%E6%95%B0%EF%BC%88%E5%94%AF%E4%B8%80%E5%80%BC%E6%95%B0%E9%87%8F%EF%BC%89%EF%BC%8C%E5%9C%A8%E4%BF%9D%E6%8C%81%E9%AB%98%E7%B2%BE%E5%BA%A6%E7%9A%84%E5%90%8C%E6%97%B6%E6%98%BE%E8%91%97%E9%99%8D%E4%BD%8E%E5%AD%98%E5%82%A8%E7%A9%BA%E9%97%B4%E5%92%8C%E8%AE%A1%E7%AE%97%E8%B5%84%E6%BA%90%E6%B6%88%E8%80%97%E3%80%82

核心功能与特性

• 高效基数估计：通过HyperLogLog算法，以较小的存储空间（通常每个集合几KB）实现对海量数据的唯一值数量估算，误差率可控制在1-2%以内
• 原生PostgreSQL集成：作为PostgreSQL扩展，支持标准SQL语法调用，可与现有数据库架构无缝集成
• 低资源消耗：相比传统COUNT(DISTINCT)操作，显著降低内存占用和计算时间，尤其适合大数据量场景
• 支持增量更新：可通过hll_add_agg等函数实现基数的增量计算和合并

使用场景与适用范围

• 用户行为分析：统计网站/应用的独立访客数（UV）、独立设备数等
• 日志分析：计算不同IP、用户ID、事件类型的唯一出现次数
• 大数据集合基数统计：如电商平台商品浏览量去重、广告曝光量统计等
• 实时数据处理：对高吞吐量数据流进行实时基数监控和分析

使用方法与配置说明

基本使用（Docker Run）

bash
# 拉取镜像（假设镜像名称为postgres-hll）
docker pull postgres-hll

# 运行容器
docker run -d \
  --name postgres-hll-instance \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_DB=your_db \
  -p 5432:5432 \
  postgres-hll

启用HLL扩展

容器启动后，通过psql连接数据库并启用扩展：

sql
-- 连接数据库
psql -h localhost -U your_user -d your_db

-- 启用hll扩展
CREATE EXTENSION hll;

HLL功能示例

sql
-- 创建测试表
CREATE TABLE user_visits (
  id SERIAL PRIMARY KEY,
  user_id INT,
  visit_time TIMESTAMP
);

-- 插入测试数据
INSERT INTO user_visits (user_id, visit_time) 
VALUES (1, NOW()), (2, NOW()), (1, NOW() + INTERVAL '1 hour'), (3, NOW());

-- 使用hll计算唯一用户数（基数）
SELECT hll_cardinality(hll_add_agg(hll_hash_integer(user_id))) AS unique_users 
FROM user_visits;
-- 结果应为3（用户1、2、3）

环境变量配置

支持PostgreSQL官方镜像的所有标准环境变量，主要包括：

• POSTGRES_PASSWORD：数据库超级用户密码（必填）
• POSTGRES_USER：数据库超级用户名（默认：postgres）
• POSTGRES_DB：初始化的数据库名称（默认与POSTGRES_USER相同）
• PGDATA：PostgreSQL数据存储路径（默认：/var/lib/postgresql/data）

Docker Compose配置示例

yaml
version: '3.8'
services:
  postgres-hll:
    image: postgres-hll
    container_name: postgres-hll
    environment:
      POSTGRES_PASSWORD: secure_password
      POSTGRES_USER: app_user
      POSTGRES_DB: analytics_db
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:

扩展信息

• 扩展项目地址：https://github.com/citusdata/postgresql-hll
• 支持的PostgreSQL版本：根据镜像标签确定，通常支持PostgreSQL 10+
• 详细函数文档：可参考https://github.com/citusdata/postgresql-hll#functions