Metadata-Version: 2.5
Name: factcat
Version: 0.6.0
Summary: Open-source alternative to Amplitude and Mixpanel that runs in your own data warehouse
Project-URL: Homepage, https://factcat.dev
Project-URL: Documentation, https://factcat.dev
Project-URL: Source, https://github.com/gordonkjlee/factcat
Project-URL: Changelog, https://github.com/gordonkjlee/factcat/blob/main/packages/engine/CHANGELOG.md
Project-URL: Issues, https://github.com/gordonkjlee/factcat/issues
Author: Gordon Lee
License: MIT
Keywords: analytics,dbt,funnel,retention,sql,warehouse
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markdown>=3.6.0
Requires-Dist: sqlglot>=25.0.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: uvicorn>=0.27.0
Provides-Extra: all
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == 'all'
Requires-Dist: snowflake-connector-python[secure-local-storage]>=3.12.0; extra == 'all'
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == 'bigquery'
Provides-Extra: dev
Requires-Dist: duckdb>=1.0.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python[secure-local-storage]>=3.12.0; extra == 'snowflake'
Description-Content-Type: text/markdown

# factcat

[![CI](https://github.com/gordonkjlee/factcat/actions/workflows/ci.yml/badge.svg)](https://github.com/gordonkjlee/factcat/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/factcat)](https://pypi.org/project/factcat/) [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](https://github.com/gordonkjlee/factcat/blob/main/LICENSE)

An open-source alternative to Amplitude and Mixpanel that runs in your own data
warehouse. Factcat generates SQL and runs it in your BigQuery (or Snowflake,
experimental) — no SDK, no ingestion, nothing hosted.

**Point it at an events table you already have** — one row per event, properties
as real columns. Python 3.10+ and credentials for your warehouse.

```bash
pip install "factcat[bigquery]"
cd /path/to/your/warehouse   # your mapping is saved here
factcat
```

That gives you a `factcat` command. Open http://127.0.0.1:8000. Setup asks which
table, which column identifies the thing you are counting, and which column is
the event timestamp. Then you have a chart.

Product analytics tools make your modelling decisions for you: `entity = a user`,
`period = a calendar bucket`, `retained = did an event`. Real definitions violate
all three, so Factcat makes all three yours:

```python
from factcat import RetentionSpec, retention_sql

spec = RetentionSpec(
    table="analytics.fct_subscription_payments",
    entity="subscription_id",   # not the user
    entity_time="sub_start",
    event_time="paid_at",
    period_days=35,             # a billing cycle plus dunning, not a calendar bucket
    n_periods=12,
    retained="status = 'collected' AND within_period_offset <= 5",
)

print(retention_sql(spec, dialect="snowflake"))
```

`retained` is arbitrary SQL over any column in your table, plus the derived columns
`offset_days`, `period_index` and `within_period_offset`.

**Status.** Factcat is 0.x. The SQL-generation API — `RetentionSpec`, `FunnelSpec`,
`EventsSpec` and the `*_sql` functions — is the surface that stays stable. A minor
release may change those dataclasses or the shape of `.factcat.json`, and says so at
the top of its release notes; a patch release never does. Pin with `factcat~=0.5.0`.

**Warehouses.** `pip install factcat` is SQL generation plus the local chart and
includes no warehouse SDK; `factcat[bigquery]` and `factcat[snowflake]` add the
official driver, `factcat[all]` adds every shipped one. BigQuery ships today;
**Snowflake is experimental** — its SQL is generated and compiled in CI against
Snowflake's grammar, but no live Snowflake account has ever executed it, so treat a
first run as a test. SQL generation alone also targets DuckDB, Postgres, Databricks,
Spark, Trino, Presto, ClickHouse and Redshift.

**Managed tables.** Factcat may create `fc_` tables in a write dataset you choose,
to make repeated breakdowns cheap; they hold entity ids and column values copied
from your events table, and they live in your warehouse. See the setup guide.

Long documentation: https://factcat.dev · Releases:
https://github.com/gordonkjlee/factcat/releases · Bugs and feedback:
https://github.com/gordonkjlee/factcat/issues
