First Database with CLI

Let’s build and query a database using the Matchy CLI.

Create input data

First, create a CSV file with some sample data. Create a file called threats.csv:

key,threat_level,category
192.0.2.1,high,malware
203.0.113.0/24,medium,botnet
*.evil.com,high,phishing
malicious-site.com,critical,c2_server

Each row defines an entry:

• key - IP address, CIDR range, pattern, or exact string
• Other columns become data fields associated with the entry

Build the database

Use matchy build to create a database:

$ matchy build threats.csv --input-format csv --output threats.mxy
Building database from threats.csv
  Added 4 entries
  Database size: 2,847 bytes
Successfully wrote threats.mxy

This creates threats.mxy, a binary database file.

Query the database

Now query it with matchy query:

$ matchy query threats.mxy 192.0.2.1
Found: IP address 192.0.2.1
  threat_level: "high"
  category: "malware"

The CLI automatically detects that 192.0.2.1 is an IP address and performs an IP lookup.

Query a CIDR range

IPs within a CIDR range match that range:

$ matchy query threats.mxy 203.0.113.42
Found: IP address 203.0.113.42 (matched 203.0.113.0/24)
  threat_level: "medium"
  category: "botnet"

Query a pattern

Patterns match using wildcards:

$ matchy query threats.mxy phishing.evil.com
Found: Pattern match
  Matched patterns: *.evil.com
  threat_level: "high"
  category: "phishing"

The domain phishing.evil.com matches the pattern *.evil.com.

Query an exact string

Exact strings must match completely:

$ matchy query threats.mxy malicious-site.com
Found: Exact string match
  threat_level: "critical"
  category: "c2_server"

Inspect the database

Use matchy inspect to see what’s inside:

$ matchy inspect threats.mxy
Database: threats.mxy
Size: 2,847 bytes
Match mode: CaseInsensitive

IP entries: 2
String entries: 1
Pattern entries: 1

Benchmark performance

Run a synthetic combined benchmark with matchy bench:

$ matchy bench combined

The command prints measurements from the current machine and generated workload. Record its version, options, cache state, and concurrent system load when comparing runs.

Input formats

The CLI supports multiple input formats:

• Text - One indicator per line
• CSV - Comma-separated values (shown above)
• JSON - JSON array of entries with metadata
• MISP - MISP threat intelligence JSON

See Input File Formats for details.

What just happened?

You just:

1. Created a CSV file with threat data
2. Built a binary database (threats.mxy)
3. Queried IPs, CIDR ranges, patterns, and exact strings
4. Inspected the database structure
5. Benchmarked query performance

The database opens through memory mapping without whole-file deserialization. Opening and query performance still depend on the deployment, so benchmark the representative database and workload before setting production targets.

Going further

• CLI Commands Reference - Complete CLI documentation
• Input File Formats - All supported input formats
• Matchy Guide - Deeper dive into Matchy concepts

To integrate Matchy into your application code, see Using the API.