Fraud Detection with Feast and MongoDB
When building ML systems, you may need the exact same feature definitions, such as a user's recent transaction patterns computed in two very different contexts. At training time, you need historical features assembled co
When building ML systems, you may need the exact same feature definitions, such as a user's recent transaction patterns computed in two very different contexts. At training time, you need historical features assembled correctly, without accidentally mixing past and future data (point-in-time correctness). At serving time, when a transaction happens, you need the current value of those same features computed and returned in milliseconds, not seconds.
Most teams achieve this by running three separate databases: the application's primary database, a dedicated low-latency online store for serving, and a separate data warehouse for offline training retrieval. Feast, combined with MongoDB, solves this by defining features once and serving them consistently in both contexts. MongoDB can act as both Feastβs online and offline store, removing the need for separate systems.
Feast is the leading open-source feature store for machine learning, which MongoDB supports as an online and offline store. This enables machine learning teams to serve features at low latency and generate point-in-time-correct training datasets directly against MongoDB.
This tutorial only configures MongoDB as Feast's online store; the offline store uses a local Parquet file (
offline_store: type: fileinfeature_store.yaml). MongoDB can also serve as Feast's offline store to fully realize the single-cluster, ETL-free architecture described above.
In this tutorial, we will build a fraud detection pipeline using MongoDB as Feastβs online store with the Django MongoDB Backend.
Specifically, you will learn:
- How to use the Django MongoDB backend to model and persist transactions in MongoDB
- How to use Feast as a feature store, with a local Parquet file as the offline store
- How to use MongoDB as Feast's online store for low-latency lookups
- How to build a statistical model (a z-score on transaction amount) to identify potentially fraudulent transactions in real time
In the end, you will use user_id to fetch a user's most recent materialized features from MongoDB (online store) using Feast and return whether that transaction looks fraudulent or not.
There are two ways to follow this tutorial.
- Option A: Clone the GitHub repo containing the finished code from this tutorial, set it up using the repo's README, and explore it on your own.
- Option B: Start the project from scratch by following the steps below.
Outline
- Prerequisites
- Create a project folder and virtual environment
- Create the Django project and Django app
- Generate synthetic financial data
- Define the Transaction model
- Load the synthetic data into MongoDB
- Scaffold the feature repository with Feast
- Define the Transaction features
- Configure Feast to use MongoDB
- Train a fraud model
- Materialize features into MongoDB
- View the materialized features in MongoDB Atlas
- Produce real-time predictions
- Conclusion and next steps
Prerequisites
Before starting, make sure you have:
- Python 3.12+
- A MongoDB Atlas cluster; a local Atlas deployment (connection string
mongodb://localhost:27017/?directConnection=true) also works.
Once these prerequisites are complete, the next step is to create your project folder.
Create a project and virtual environment
Create an empty folder for your project and cd into it.
mkdir fraud_detection
cd fraud_detection
From the project root, create a virtual environment:
python3 -m venv .venv
Then activate it.
On macOS/Linux:
Run source .venv/bin/activate
On Windows:
Run .venv\Scripts\activate
Install dependencies
Create a requirements.txt file at the root of the project with the following contents:
# requirements.txt
django-mongodb-backend==6.0.4
python-dotenv==1.2.4
feast==0.67.0
pymongo==4.19.0
pandas==2.3.3
numpy==2.5.4
pyarrow==26.0.0
django-mongodb-backend 6.0.x installs Django 6.0, which matches the 6.0.x project template used in the next step.
Then install everything:
pip install -r requirements.txt
Create Django Project and Django App
From your project's root directory, run the following command to create a new Django project from the MongoDB project template. The . after the project name tells Django to create the project in the current directory instead of a new nested folder.
django-admin startproject fraud_detection . --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip
The template adds a README.md, but it doesnβt overwrite your requirements.txt.
Create the transactions app
python manage.py startapp transactions
Register the app in fraud_detection/settings.py by adding transactions to the end of the existing INSTALLED_APPS list. The template already has the other entries:
INSTALLED_APPS = [
'fraud_detection.apps.MongoAdminConfig',
'fraud_detection.apps.MongoAuthConfig',
'fraud_detection.apps.MongoContentTypesConfig',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'django_mongodb_backend',
'transactions',
]
Configure environment variables
Create a .gitignore file at the root of the project so that secrets and generated files are not added when you push.
#.gitignore
.env
.venv/
__pycache__/
*.pyc
data/transactions.parquet
training/model_params.json
feature_repo/feature_repo/data/registry.db
Then create a .env file at the root of the project with your own values.
# .env
SECRET_KEY='<your-secret-key>'
MONGODB_URI='mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority'
DB_NAME='fraud_detection'
NB: Keep the single quotes.
For SECRET_KEY, copy the value Django generated in settings.py when you ran startproject, or generate a new one:
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
Django hardcodes the secret key in settings.py by default, but we move it into .env to keep it out of version control, since it's used to sign session cookies, CSRF tokens, and other security-sensitive data.
Now, update fraud_detection/settings.py to read the secret key and the database configuration from the environment instead of hardcoding them. Make the following changes and leave the rest of the file as is.
At the top of the file, add the imports and the load_dotenv() call:
import os
from dotenv import load_dotenv
load_dotenv()
Replace the hardcoded SECRET_KEY = '...' line with:
SECRET_KEY = os.getenv('SECRET_KEY')
In the existing DATABASES setting, replace the HOST and NAME values:
DATABASES = {
'default': {
'ENGINE': 'django_mongodb_backend',
'HOST': os.getenv("MONGODB_URI"),
'NAME': os.getenv("DB_NAME"),
},
}
Generate synthetic financial data
Since we don't have a real transaction feed, we'll generate a small synthetic dataset with a handful of users, categories, and locations, plus a small percentage of inflated-amount "fraudulent" transactions.
First, create a data/ directory at the root of the project (alongside manage.py) to hold this script and the generated file:
mkdir data
Then create data/generate_transactions.py with the following contents:
"""Generates random transactions data for the Feast + MongoDB tutorial."""
from pathlib import Path
import pandas as pd
import numpy as np
TRANSACTIONS_PARQUET_FILE = Path(__file__).resolve().parent / "transactions.parquet"
random_generator = np.random.default_rng(seed=42)
N, FRAUD_RATE = 50, 0.02
df = pd.DataFrame({
"user_id": random_generator.integers(1, 9, N),
"transaction_id": [f"txn_{i:04d}" for i in range(N)],
"amount": random_generator.lognormal(mean=3.5, sigma=0.6, size=N).round(2),
"category": random_generator.choice(["food", "utilities", "entertainment", "travel", "shopping"], size=N),
"location": random_generator.choice(["Accra", "Lagos", "New York", "London", "Paris"], size=N),
# Timezone-aware: Django runs with USE_TZ = True, and Feast expects UTC.
"event_timestamp": pd.Timestamp("2026-07-01", tz="UTC") + pd.to_timedelta(random_generator.integers(0, 30 * 24 * 60, N), unit="m"),
}).sort_values("event_timestamp").reset_index(drop=True)
# Choose a fraud row from each user's most recent transactions
latest_per_user = df.groupby("user_id").tail(1)
fraud_indices = latest_per_user.sample(n=max(1, round(N * FRAUD_RATE)), random_state=42).index
df["is_fraudulent"] = False
df.loc[fraud_indices, "is_fraudulent"] = True
# Inflate the amount for fraudulent transactions
df.loc[fraud_indices, "amount"] *= random_generator.uniform(5, 10, len(fraud_indices))
df["created_timestamp"] = df["event_timestamp"]
df.to_parquet(TRANSACTIONS_PARQUET_FILE, index=False)
print(f"Wrote {len(df)} transactions to parquet file, {df['is_fraudulent'].sum()} of which are fraudulent.")
Feast requires an event_timestamp column (when the fact occurred) and, since we're using a FileSource, a created_timestamp column (when the row was written) for tie-breaking. The timestamps are timezone-aware (UTC) because Django runs with USE_TZ = True and Feast works in UTC.
Run the script from the project root:
python data/generate_transactions.py
The expected output should be Wrote 50 transactions to parquet file, 1 of which are fraudulent.
This writes data/transactions.parquet, which is used both to load data into MongoDB via the Django ORM and as Feast's offline store for training.
Define the Transaction model
transactions/models.py defines the Django model that maps to the transactions collection in MongoDB:
from django.db import models
class Transaction(models.Model):
transaction_id = models.CharField(max_length=64, unique=True)
user_id = models.IntegerField()
amount = models.DecimalField(max_digits=10, decimal_places=2)
category = models.CharField(max_length=100)
location = models.CharField(max_length=100)
timestamp = models.DateTimeField()
is_fraudulent = models.BooleanField(default=False)
class Meta:
db_table = 'transactions'
indexes = [
models.Index(fields=['user_id']),
models.Index(fields=['timestamp']),
]
def __str__(self):
return f"Transaction {self.transaction_id} - Amount: {self.amount} - Fraudulent: {self.is_fraudulent}"
user_id is an IntegerField so that it matches the Feast entity's INT64 type and the <int:user_id> URL parameter we will define later. It is also indexed because the app looks up transactions by user.
Generate and run the migration
python manage.py makemigrations transactions
python manage.py migrate
Load the synthetic data into MongoDB
Create the folders for the custom management command:
mkdir -p transactions/management/commands
touch transactions/management/__init__.py
touch transactions/management/commands/__init__.py
transactions/management/commands/load_transactions.py is a custom management command that reads data/transactions.parquet and bulk-inserts the rows into MongoDB through the Django ORM:
from decimal import Decimal
import pandas as pd
from django.conf import settings
from django.core.management.base import BaseCommand
from transactions.models import Transaction
class Command(BaseCommand):
help = "Loading transaction data from data/transactions.parquet into the database via Django ORM"
def add_arguments(self, parser):
parser.add_argument(
"--path",
default=settings.BASE_DIR/"data"/"transactions.parquet",
help="Path to the Parquet file containing transaction data",
)
def handle(self, *args, **options):
df = pd.read_parquet(options["path"])
transactions = [
Transaction(
user_id=int(row["user_id"]),
transaction_id=row["transaction_id"],
amount=Decimal(f"{row['amount']:.2f}"),
category=row["category"],
location=row["location"],
timestamp=row["event_timestamp"],
is_fraudulent=bool(row["is_fraudulent"]),
)
for row in df.to_dict("records")
]
Transaction.objects.all().delete()
Transaction.objects.bulk_create(transactions)
self.stdout.write(
self.style.SUCCESS(
f" Loaded {len(transactions)} transactions into MDB database."
)
)
A few details to note:
-
amountis converted to aDecimalwith two decimal places to match theDecimalField. - Existing transactions are deleted before inserting, so you can re-run the command after regenerating the data without hitting the unique constraint on
transaction_id. - The default
--pathis built fromsettings.BASE_DIRso that the command will find the Parquet file no matter which directory you run it from.
Then run it:
python manage.py load_transactions
Scaffold the feature repository with Feast
Before we go ahead to define features, we need to initialize a Feast project. From the root of your directory, run:
feast init feature_repo
This generates a demo Feast project in feature_repo/feature_repo/. Alongside the feature_store.yaml configuration file, it includes three things you won't need for this tutorial:
-
feature_definitions.py: example feature definitions for the demo dataset -
test_workflow.py: a script that runs through the demo end to end -
data/driver_stats.parquetanddata/driver_quality_labels.parquet: sample data for the demo
Delete these files, but keep the data/ folder, since Feast stores its registry there. You'll replace the demo definitions with your own features.py (below) and update feature_store.yaml as shown in "Configure Feast to use MongoDB".
feast init also creates feature_repo/README.md and feature_repo/.gitignore. You can delete them or leave them; they donβt affect anything.
Define the Transaction features
Feast needs its own definitions of the entity and features, independent of the Django model, because it reads directly from the Parquet file rather than through the Django ORM. These live in feature_repo/feature_repo/features.py:
from datetime import timedelta
from pathlib import Path
from feast import Entity, FeatureView, Field, FileSource
from feast.types import Float32, String
from feast.value_type import ValueType
# An entity is the key used to look up features; here, it is the user_id
user = Entity(
name="user_id",
join_keys=["user_id"],
value_type=ValueType.INT64,
)
# Feast reads the Parquet file directly; it does not go through the Django ORM.
TRANSACTIONS_PARQUET_FILE = (
Path(__file__).resolve().parents[2] / "data" / "transactions.parquet"
)
transaction_source = FileSource(
name="transaction_source",
path=str(TRANSACTIONS_PARQUET_FILE),
timestamp_field="event_timestamp",
created_timestamp_column="created_timestamp",
)
transaction_features = FeatureView(
name="transaction_features",
entities=[user],
ttl=timedelta(days=365),
schema=[
Field(name="amount", dtype=Float32),
Field(name="category", dtype=String),
Field(name="location", dtype=String),
],
source=transaction_source,
)
-
useris the entity: the key (user_id) that features are looked up by. -
transaction_sourcepoints Feast to the generated Parquet file.timestamp_fieldtells Feast which column holds the event time used for point-in-time joins, andcreated_timestamp_columnbreaks ties when two rows share the same event time. -
transaction_featuresis the feature view that ties the entity, the source, and the individual fields (amount,category,location) together.
Configure Feast to use MongoDB
Feast's project configuration lives in feature_repo/feature_repo/feature_store.yaml:
project: fraud_detection
registry: data/registry.db
provider: local
offline_store:
type: file
online_store:
type: mongodb
connection_string: ${MONGODB_URI}
database_name: ${DB_NAME}
entity_key_serialization_version: 3
-
offline_store.type: filetells Feast to use the local Parquet file for historical/training queries. -
online_store.type: mongodbtells Feast to use MongoDB for low-latency online lookups, using the sameMONGODB_URIconnection string andDB_NAMEdatabase as Django.
Feast substitutes ${MONGODB_URI} and ${DB_NAME} from the process environment. Unlike Django, the feast CLI does not read your .env file (it never imports settings.py), so export the variables into your shell first.
On macOS/Linux, from the project root:
set -a; source .env; set +a
If you skip this, Feast wonβt raise an error about missing variables. It leaves ${MONGODB_URI} and ${DB_NAME} as literal text, and the next command fails with a confusing error such as pymongo.errors.InvalidName: database names cannot contain the character '$'.
On Windows, set them in your shell instead, for example $env:MONGODB_URI="..." and $env:DB_NAME="..." in PowerShell. Run all of the following feast and Python commands from this same shell.
From the project root, register the entity and feature view with Feast:
cd feature_repo/feature_repo
feast apply
This creates or updates data/registry.db with your entity and feature view definitions.
Train a fraud model
Return to the root after feast apply.
cd ../..
From the project root, create a training/ folder to contain the training script and the model parameters it produces:
mkdir training
training/train_model.py pulls point-in-time-correct historical features from Feast's offline store and derives the parameters for a simple z-score model:
A z-score measures how many standard deviations a value sits from the mean. Transaction amounts are right-skewed (a few large purchases, many small ones), so we compute the z-score on log(amount), which is roughly normally distributed. The mean and standard deviation are fit on legitimate transactions only and transactions with log-amounts more than 2 standard deviations above the mean are flagged as potentially fraudulent.
For each row in entity_df, get_historical_features() looks backward from that row's timestamp and finds the most recent feature value available at that point in time, which is what makes the result point-in-time-correct.
If no feature value exists within the ttl window before a given timestamp, that row comes back with nulls instead of a stale, overly-old value. Shortening the ttl makes the lookup stricter, as only recent data will be added; lengthening it allows older values to still be considered valid.
"""
Retrieves point-in-time training data from Feastβs offline store, then
βtrainsβ a z-score model on it.
The model parameters are written to training/model_params.json so that the
Django view reads them instead of having to copy them in by hand.
"""
import json
from pathlib import Path
import numpy as np
import pandas as pd
from feast import FeatureStore
BASE_DIR = Path(__file__).resolve().parent.parent
TRANSACTIONS_PARQUET_FILE = BASE_DIR / "data" / "transactions.parquet"
PARAMS_PATH = Path(__file__).resolve().parent / "model_params.json"
store = FeatureStore(repo_path=str(BASE_DIR / "feature_repo" / "feature_repo"))
transactions_df = pd.read_parquet(TRANSACTIONS_PARQUET_FILE)
# Extra entity_df columns (here, the is_fraudulent label) are passed through to the result unchanged.
entity_df = transactions_df[["user_id", "event_timestamp", "is_fraudulent"]].copy()
training_df = store.get_historical_features(
entity_df=entity_df,
features=[
"transaction_features:amount",
"transaction_features:category",
"transaction_features:location",
],
).to_df()
print(training_df.head(10))
print(f"\nPulled {len(training_df)} rows of training data.")
# --- The βmodelβ: mean and standard deviation of log(amount) ---
# Amounts are right-skewed (lognormal), so the z-score is computed on
# log(amount), which is roughly normal. The baseline is fit on legitimate
# transactions only, so fraud doesnβt inflate its own threshold.
# A transaction is flagged if its log-amount is more than 2 standard
# deviations ABOVE the mean (one-sided: unusually small amounts arenβt flagged).
legit_log_amounts = np.log(training_df.loc[~training_df["is_fraudulent"], "amount"])
TRAIN_MEAN_LOG_AMOUNT = float(legit_log_amounts.mean())
TRAIN_STD_LOG_AMOUNT = float(legit_log_amounts.std())
PARAMS_PATH.write_text(
json.dumps(
{
"mean_log_amount": TRAIN_MEAN_LOG_AMOUNT,
"std_log_amount": TRAIN_STD_LOG_AMOUNT,
"z_score_threshold": 2.0,
},
indent=2,
)
+ "\n"
)
print(f"\nFit on {len(legit_log_amounts)} legitimate transactions.")
print("Trained model parameters:")
print(f"TRAIN_MEAN_LOG_AMOUNT = {TRAIN_MEAN_LOG_AMOUNT}")
print(f"TRAIN_STD_LOG_AMOUNT = {TRAIN_STD_LOG_AMOUNT}")
print(f"\nWrote parameters to {PARAMS_PATH}")
From the project root, run:
python training/train_model.py
With the seeded data, you should see Fit on 49 legitimate transactions. , TRAIN_MEAN_LOG_AMOUNT = 3.5326β¦, and TRAIN_STD_LOG_AMOUNT = 0.4687β¦.
The script writes these values to training/model_params.json, which the Django view reads at request time. training/model_params.json is already in your .gitignore; it's regenerated each time you train.
Materialize features into MongoDB
"Materializing" pushes the latest feature values for each entity from the offline store to the online store (MongoDB), which is what serves low-latency lookups at request time.
From the project root, run:
cd feature_repo/feature_repo
feast materialize 2020-01-01T00:00:00 2026-09-01T00:00:00
The end date must be after the most recent event_timestamp in your data (30 July 2026 for seeded data).
You should see output similar to the following along with a progress bar:
Materializing 1 feature view from 2020-01-01 00:00:00+00:00 to 2026-09-01 00:00:00+00:00 into the mongodb online store.
transaction_features:
You can confirm the features landed in MongoDB by using Feast to read them back.
Create feature_repo/feature_repo/test_online_features.py:
"""
Confirms Feast can read materialized features back out of MongoDB
via get_online_features()
"""
from pathlib import Path
from feast import FeatureStore
def main():
store = FeatureStore(repo_path=str(Path(__file__).resolve().parent))
entity_rows = [{"user_id": 2}]
online_features = store.get_online_features(
features=[
"transaction_features:amount",
"transaction_features:category",
"transaction_features:location",
],
entity_rows=entity_rows,
).to_dict()
print(online_features)
if __name__ == "__main__":
main()
The work is wrapped in main() behind an if __name__ == "__main__": guard because feast apply imports every Python file in the feature repository. Without the guard, this script would query the online store every time you run feast apply.
You are still in feature_repo/feature_repo, so run the following command and return to the project root:
python test_online_features.py
cd ../..
You should see something like this:
{'user_id': [2], 'amount': [28.079999923706055], 'category': ['entertainment'], 'location': ['London']}
The online store holds each entity's latest value only, not full history, so a flagged transaction won't necessarily surface if newer transactions have since materialized over it. Re-run
feast materializewhenever new transactions are generated and loaded.
View the materialized features in MongoDB Atlas
After connecting to your MongoDB Atlas cluster, open your cluster and browse collections.
Select the database you set as DB_NAME in .env (the same database used by Django and by database_name in feature_store.yaml).
Open the fraud_detection_latest collection. Feast names it <project>_latest, and its MongoDB online store keeps one document per entity holding only the most recent materialized feature values.
Materialized features in the fraud_detection_latest collection, one document per user. User 6βs document holds the fraudulent amount (143.044β¦).
Produce real-time predictions
Back in the Django app, transactions/feast_client.py wraps the Feast online lookup:
from django.conf import settings
from feast import FeatureStore
FEATURE_REPO_PATH = settings.BASE_DIR / "feature_repo" / "feature_repo"
_store = FeatureStore(repo_path=str(FEATURE_REPO_PATH))
def get_latest_transaction_features(user_id: int) -> dict:
"""
Looks up the most recent materialized transaction features for a
user_id from MongoDB (the online store) via Feast.
"""
result = _store.get_online_features(
features=[
"transaction_features:amount",
"transaction_features:category",
"transaction_features:location",
],
entity_rows=[{"user_id": user_id}],
).to_dict()
return {key: values[0] for key, values in result.items()}
transactions/views.py uses it to apply the z-score model trained in "Train a fraud model" section and flag potentially fraudulent transactions. It reads the model parameters from training/model_params.json:
import json
import math
from django.conf import settings
from django.http import JsonResponse
from transactions.feast_client import get_latest_transaction_features
PARAMS_PATH = settings.BASE_DIR / "training" / "model_params.json"
def _load_model_params():
with open(PARAMS_PATH) as f:
return json.load(f)
def score_transaction(request, user_id: int):
try:
params = _load_model_params()
except FileNotFoundError:
return JsonResponse(
{"error": "Model parameters not found. Run training/train_model.py first."},
status=503,
)
features = get_latest_transaction_features(user_id)
amount = features.get("amount")
if amount is None:
return JsonResponse(
{"error": f"No features found for user_id {user_id}"}, status=404
)
z_score = (math.log(amount) - params["mean_log_amount"]) / params["std_log_amount"]
is_potentially_fraudulent = z_score > params["z_score_threshold"]
return JsonResponse({
"user_id": user_id,
"amount": amount,
"category": features.get("category"),
"location": features.get("location"),
"z_score": round(z_score, 3),
"is_potentially_fraudulent": is_potentially_fraudulent,
})
From the project root, start the development server:
python manage.py runserver
In a second terminal, request a score for a given user:
curl http://127.0.0.1:8000/score/2/
You should get a JSON response like:
{
"user_id": 2,
"amount": 28.079999923706055,
"category": "entertainment",
"location": "London",
"z_score": -0.422,
"is_potentially_fraudulent": false
}
User 2βs latest transaction is normal. The seeded dataβs fraudulent transaction is user 6βs latest so we can request that by running:
curl http://127.0.0.1:8000/score/6/
Results:
{
"user_id": 6,
"amount": 143.04425048828125,
"category": "utilities",
"location": "London",
"z_score": 3.052,
"is_potentially_fraudulent": true
}
The online store holds only each userβs latest values, so an older fraudulent transaction would be overwritten by newer ones. The generator deliberately makes the fraud a userβs most recent transaction so you can see a positive result.
NB: the z-score is a baseline; it uses one baseline for all users rather than each userβs spending pattern and itβs evaluated in the same data it was trained on with no test set.
Conclusion and next steps
Great job on making it to this point π. You've built an end-to-end pipeline that generates transaction data, stores it in MongoDB through Django, defines and registers features with Feast, trains a statistical model on historical features, materializes the latest feature values into MongoDB as an online store, and serves real-time fraud scores from a Django view.
From here, you could explore:
- Replace the z-score model with a trained scikit-learn classifier (
pip install scikit-learn). - Add more features such as the average spend per user to
transaction_features. - Schedule
feast materialize-incrementalto run on a cron job so the online store stays up to date as new transactions are loaded. - Add authentication and input validation to the
score_transactionendpoint.
References
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.