ftmq

This library provides methods to query and filter entities formatted as Follow The Money data, either from a json file/stream or using a statement-based store backend from nomenklatura.

It also provides a Query class that can be used in other libraries to work with SQL store queries or api queries.

ftmq.Query is the central query hub of the OpenAleph ecosystem: one backend-agnostic query object that filters FtM streams and stores, translates to SQL, and bridges to the OpenAleph API.

To get familiar with the Follow The Money ecosystem, you can have a look at this pad here.

Installation

Minimum Python version: 3.11

pip install ftmq

Usage

Command line

cat entities.ftm.json | ftmq -q 'filter:schema=Company&filter:properties.country=de&filter:gte:properties.incorporationDate=2023' -o s3://data/entities-filtered.ftm.json

Python Library

from ftmq import Query, M, P, G, smart_read_proxies

# Legal entities in the `companies` dataset that are based in Germany, or in
# Austria and incorporated since 2020, but never the dissolved ones, return the
# 5 most recent incorporated ones:
q = Query().where(
    M(dataset="companies"),
    M(schemata="LegalEntity"),
    G(countries="de") | (G(countries="at") & P(incorporationDate__gte=2020)),
    ~P(status__ilike="%dissolved%"),
).order_by("incorporationDate", ascending=False)[:5]

for proxy in smart_read_proxies("s3://data/entities.ftm.json"):
    if q.apply(proxy):
        yield proxy

Full-text search

ftmq.search (formerly the standalone ftmq-search package) indexes entities into simple full-text search stores, backed by SQLite FTS5 or Tantivy (pip install ftmq[search]):

cat entities.ftm.json | ftmq search transform | ftmq search --uri sqlite:///ftmqs.db index
ftmq search --uri sqlite:///ftmqs.db "jane doe"

HTTP API

ftmq.api (formerly the standalone ftmq-api package) exposes a store and its search index as a read-only FastAPI application (pip install ftmq[api]), speaking the Aleph filter grammar:

granian --interface asgi ftmq.api.app:app
curl "localhost:8000/entities?filter:schema=Payment&filter:gte:properties.date=2023"

Documentation

https://docs.investigraph.dev/lib/ftmq

Support

This project is part of investigraph

In 2023, development of ftmq was supported by Media Tech Lab Bayern batch #3

License and Copyright

ftmq, (C) 2023 Simon Wörpel ftmq, (C) 2024-2025 investigativedata.io ftmq, (C) 2025 Data and Research Center – DARC

ftmq is licensed under the AGPLv3 or later license.

Prior to version 0.8.0, ftmq was released under the MIT license.

see NOTICE and LICENSE