Download the PHP package inerba/filament-natural-language-filter without Composer

Filament Natural Language Filter

A simple Filament filter that converts natural language text into database queries using AI.

Installation

Configuration

1. Publish the config file:

2. Add your AI provider configuration to your .env file:

Usage

Add the filter to your Filament table:

Advanced Features

Relationship Filtering

Boolean Logic Support

Aggregation Queries

Real-World Implementation Examples

E-commerce Product Management

User Management System

Content Management System

Order Management System

Advanced Configuration Examples

Custom Column Mappings

Performance Optimization

Multi-Language Support

Code Implementation Patterns

Custom Filter Logic

Integration with Other Filters

API Integration

Search Modes

You can configure how the filter triggers searches:

Submit Mode (Default) - Search on Enter key

Live Mode - Search as you type

Manual Mode Configuration

When to Use Each Mode

Submit Mode (Default) - Best for:

• Large datasets where live search might be slow
• Complex queries that users want to perfect before searching
• Reducing API calls to OpenAI (only search when user is ready)

Live Mode - Best for:

• Instant feedback and better user experience
• Smaller datasets where performance isn't a concern
• Users who prefer immediate results as they type

How it works

1. User enters natural language: "show users named john created after 2023"
2. AI processes the text: Converts it to structured filters based on your available columns
3. Database query is built: WHERE name LIKE '%john%' AND created_at > '2023-01-01'
4. Results are filtered: Table shows matching records

Examples

Basic Filtering Examples

Simple Text Searches:

• "users named john" → WHERE name LIKE '%john%'
• "active users" → WHERE status = 'active'
• "email contains gmail" → WHERE email LIKE '%gmail%'
• "products in electronics" → WHERE category LIKE '%electronics%'

Date Filtering:

• "created after 2023" → WHERE created_at > '2023-01-01'
• "created yesterday" → WHERE DATE(created_at) = '2023-12-31'
• "created this week" → WHERE created_at >= '2023-12-25'
• "created between january and march" → WHERE created_at BETWEEN '2023-01-01' AND '2023-03-31'

Numeric Comparisons:

• "orders over $100" → WHERE amount > 100
• "users with age between 18 and 65" → WHERE age BETWEEN 18 AND 65
• "products with price less than 50" → WHERE price < 50

Advanced Relationship Filtering

Cross-Model Queries:

Relationship Examples:

• "users with orders over $100" → WHERE EXISTS (SELECT 1 FROM orders WHERE user_id = users.id AND amount > 100)
• "posts by active users" → WHERE EXISTS (SELECT 1 FROM users WHERE id = posts.user_id AND status = 'active')
• "products in electronics category" → WHERE EXISTS (SELECT 1 FROM categories WHERE id = products.category_id AND name = 'electronics')
• "users with more than 5 posts" → WHERE (SELECT COUNT(*) FROM posts WHERE user_id = users.id) > 5

Boolean Logic Examples

AND Operations:

• "active users AND created after 2023" → WHERE status = 'active' AND created_at > '2023-01-01'
• "users with gmail email AND verified" → WHERE email LIKE '%gmail%' AND verified = 1

OR Operations:

• "users named john OR email contains gmail" → WHERE name LIKE '%john%' OR email LIKE '%gmail%'
• "status is pending OR status is processing" → WHERE status = 'pending' OR status = 'processing'

Complex Logic:

• "status is pending AND (amount > 100 OR priority is high)" → WHERE status = 'pending' AND (amount > 100 OR priority = 'high')
• "active users AND (created this year OR has orders)" → WHERE status = 'active' AND (YEAR(created_at) = 2023 OR EXISTS (SELECT 1 FROM orders WHERE user_id = users.id))

Aggregation Query Examples

Count Operations:

• "top 10 users by order count" → SELECT users.*, COUNT(orders.id) as order_count FROM users LEFT JOIN orders ON users.id = orders.user_id GROUP BY users.id ORDER BY order_count DESC LIMIT 10
• "users with more than 5 posts" → WHERE (SELECT COUNT(*) FROM posts WHERE user_id = users.id) > 5

Sum/Average Operations:

• "products with highest sales" → SELECT products.*, SUM(order_items.quantity) as total_sales FROM products JOIN order_items ON products.id = order_items.product_id GROUP BY products.id ORDER BY total_sales DESC
• "users with average order value over $200" → WHERE (SELECT AVG(amount) FROM orders WHERE user_id = users.id) > 200

Min/Max Operations:

• "oldest users" → ORDER BY created_at ASC
• "newest products" → ORDER BY created_at DESC
• "highest priced products" → ORDER BY price DESC

Universal Language Support 🌍

The filter supports ANY language with automatic AI translation and understanding:

Multi-Language Examples

English:

• "show users named john" → WHERE name LIKE '%john%'
• "created after 2023" → WHERE created_at > '2023-01-01'

Arabic (العربية):

• "الاسم يحتوي على أحمد" → WHERE name LIKE '%أحمد%'
• "أنشئ بعد 2023" → WHERE created_at > '2023-01-01'

Spanish (Español):

• "usuarios con nombre juan" → WHERE name LIKE '%juan%'
• "creado después de 2023" → WHERE created_at > '2023-01-01'

French (Français):

• "nom contient marie" → WHERE name LIKE '%marie%'
• "créé après 2023" → WHERE created_at > '2023-01-01'

German (Deutsch):

• "benutzer mit namen hans" → WHERE name LIKE '%hans%'
• "erstellt nach 2023" → WHERE created_at > '2023-01-01'

Chinese (中文):

• "姓名包含张三" → WHERE name LIKE '%张三%'
• "2023年后创建" → WHERE created_at > '2023-01-01'

Japanese (日本語):

• "田中という名前のユーザー" → WHERE name LIKE '%田中%'
• "2023年以降に作成" → WHERE created_at > '2023-01-01'

How It Works

1. AI Language Detection: Automatically detects the input language
2. Natural Understanding: Maps language-specific keywords to operators
3. Value Preservation: Keeps original values in their native language/script
4. Mixed Language: Handles mixed-language queries seamlessly

Mixed Language Queries

The AI can handle mixed-language queries naturally:

• "name يحتوي على john" ✅
• "usuario con email gmail.com" ✅
• "姓名 contains 张三" ✅

AI Provider Support

The package supports both OpenAI and Azure OpenAI services. You can choose your preferred provider:

OpenAI (Default)

Azure OpenAI

Configuration Options

Environment Variables

For OpenAI:

For Azure OpenAI:

Advanced Features Configuration:

Version Management

The package includes automatic version management. You can bump versions manually or automatically:

Manual Version Bumping

Automatic Version Bumping

The package includes a Git pre-push hook that automatically bumps the patch version on each push to the main branch.

Quick Bump and Push

Troubleshooting & FAQ

Common Issues

1. Filter Not Working

Problem: Natural language filter doesn't process queries Solutions:

2. Slow Performance

Problem: Filter is slow with large datasets Solutions:

3. AI Not Understanding Queries

Problem: AI returns empty results or wrong filters Solutions:

4. Relationship Filtering Issues

Problem: Relationship queries don't work Solutions:

5. Cache Issues

Problem: Results are cached and not updating Solutions:

Performance Optimization

Database Indexing

Query Optimization

Caching Strategy

Debugging

Enable Debug Mode

Check Logs

Test AI Connection

Advanced Configuration

Custom AI Prompts

Rate Limiting

Custom Validation

Migration Guide

From Basic to Advanced

Updating Configuration

Best Practices

1. Column Selection

2. Relationship Management

3. Performance Monitoring

Testing

Unit Tests

Manual Testing

Test Basic Functionality

Test AI Integration

Test Relationship Filtering

Integration Tests

Performance Testing

API Testing

Contributing

Development Setup

Adding New Features

1. Create Feature Branch

2. Implement Feature

3. Add Tests

4. Update Documentation

5. Submit Pull Request

Code Style

The package follows PSR-12 coding standards:

Testing Guidelines

1. Write Tests First (TDD approach)
2. Test Edge Cases (empty queries, invalid data)
3. Test Performance (large datasets, complex queries)
4. Test Error Handling (API failures, invalid configurations)

Release Process

1. Update Version

2. Update Changelog

3. Create Release

Requirements

• PHP 8.1+
• Laravel 10+
• Filament 3+
• OpenAI API key or Azure OpenAI credentials

License

MIT