Skip to content

Commit 8238f3e

Browse files
ejsmithejsmith
committed
Update docs
1 parent d5d68c7 commit 8238f3e

File tree

7 files changed

+109
-12
lines changed

7 files changed

+109
-12
lines changed

‎AGENTS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
## Architecture Overview
44

5-
This is a Lucene query string parser that converts query strings into an AST (Abstract Syntax Tree), with support for query transformation via visitors and Entity Framework integration.
5+
This library provides dynamic Lucene-style query capabilities for .NET applications, allowing users to write powerful search queries using familiar Lucene syntax. It serves as a modern replacement for [Foundatio.Parsers](https://github.com/FoundatioFx/Foundatio.Parsers).
6+
7+
The core pipeline converts query strings into an AST (Abstract Syntax Tree), with support for query transformation via visitors. Currently supports Entity Framework Core for LINQ expression generation, with Elasticsearch support planned.
68

79
### Core Pipeline
810
```

‎README.md‎

Lines changed: 48 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
11
# Foundatio.LuceneQuery
22

3-
A high-performance Lucene query string parser for .NET that converts query strings into an Abstract Syntax Tree (AST). Supports query transformation via visitors and includes Entity Framework Core integration for generating LINQ expressions.
3+
A library for adding dynamic Lucene-style query capabilities to your .NET applications. Enable your users to write powerful search queries using familiar Lucene syntax, with support for Entity Framework Core and (coming soon) Elasticsearch.
4+
5+
This project is a modern replacement for [Foundatio.Parsers](https://github.com/FoundatioFx/Foundatio.Parsers).
46

57
## Features
68

9+
- **Dynamic User Queries** - Let users write powerful search queries using Lucene syntax
10+
- **Entity Framework Integration** - Convert Lucene queries directly to LINQ expressions for EF Core
11+
- **Elasticsearch Support** - (Coming soon) Generate Elasticsearch queries from the same syntax
712
- **Full Lucene Query Syntax** - Terms, phrases, fields, ranges, boolean operators, wildcards, regex, and more
8-
- **Elasticsearch Extensions** - Date math expressions (`now-1d`, `2024-01-01||+1M/d`), `_exists_`, `_missing_`
13+
- **Date Math Expressions** - Support for Elasticsearch-style date math (`now-1d`, `2024-01-01||+1M/d`)
914
- **Visitor Pattern** - Transform, validate, or analyze queries with composable visitors
15+
- **Field Aliasing** - Map user-friendly field names to your actual data model
16+
- **Query Validation** - Restrict allowed fields, operators, and patterns
1017
- **Round-Trip Capable** - Parse queries to AST and convert back to query strings
11-
- **Entity Framework Integration** - Convert Lucene queries directly to LINQ expressions
1218
- **Error Recovery** - Resilient parser returns partial AST with detailed error information
1319

1420
## Installation
@@ -94,20 +100,53 @@ if (!validationResult.IsValid)
94100

95101
### Entity Framework Integration
96102

103+
Enable dynamic, user-driven queries in your API endpoints:
104+
97105
```csharp
98106
using Foundatio.LuceneQuery.EntityFramework;
99107

108+
// In your API controller or service
109+
[HttpGet("employees")]
110+
public async Task<IActionResult> SearchEmployees([FromQuery] string query)
111+
{
112+
var parser = new EntityFrameworkQueryParser();
113+
114+
// User provides: "name:john AND salary:[50000 TO *] AND department:engineering"
115+
Expression<Func<Employee, bool>> filter = parser.BuildFilter<Employee>(query);
116+
117+
var results = await _context.Employees
118+
.Where(filter)
119+
.ToListAsync();
120+
121+
return Ok(results);
122+
}
123+
```
124+
125+
With field aliasing to protect your data model:
126+
127+
```csharp
100128
var parser = new EntityFrameworkQueryParser();
101129

102-
// Build a filter expression from a Lucene query
103-
Expression<Func<Employee, bool>> filter = parser.BuildFilter<Employee>(
104-
"name:john AND salary:[50000 TO *] AND isActive:true"
105-
);
130+
// Map user-friendly names to actual entity properties
131+
var fieldMap = new FieldMap
132+
{
133+
{ "name", "FullName" },
134+
{ "dept", "Department.Name" },
135+
{ "hired", "HireDate" }
136+
};
106137

107-
// Use with EF Core
108-
var results = await context.Employees.Where(filter).ToListAsync();
138+
// User query: "name:john AND dept:engineering AND hired:[2020-01-01 TO *]"
139+
Expression<Func<Employee, bool>> filter = parser.BuildFilter<Employee>(userQuery, fieldMap);
109140
```
110141

142+
## Use Cases
143+
144+
- **Search APIs** - Let users filter data with powerful query syntax
145+
- **Admin Dashboards** - Enable complex filtering without custom UI for each field
146+
- **Reporting** - Allow dynamic report criteria using familiar search syntax
147+
- **Data Export** - Let users specify exactly what data they need
148+
- **Audit/Log Search** - Search through logs with date ranges, terms, and boolean logic
149+
111150
## Supported Query Syntax
112151

113152
| Syntax | Example | Description |

‎benchmarks/Foundatio.LuceneQueryParser.Benchmarks/Foundatio.LuceneQueryParser.Benchmarks.csproj‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net10.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
<IsPackable>false</IsPackable>
9+
</PropertyGroup>
10+
11+
<ItemGroup>
12+
<PackageReference Include="BenchmarkDotNet" Version="0.14.0" />
13+
<PackageReference Include="Foundatio.Parsers.LuceneQueries" Version="7.*" />
14+
<PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="9.0.0" />
15+
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
16+
</ItemGroup>
17+
18+
<ItemGroup>
19+
<ProjectReference Include="..\..\src\Foundatio.LuceneQuery\Foundatio.LuceneQuery.csproj" />
20+
<ProjectReference Include="..\..\src\Foundatio.LuceneQuery.EntityFramework\Foundatio.LuceneQuery.EntityFramework.csproj" />
21+
</ItemGroup>
22+
23+
</Project>

‎build/common.props‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33
<PropertyGroup>
44
<TargetFrameworks>net8.0;net10.0</TargetFrameworks>
55
<Product>Foundatio</Product>
6-
<Description>Pluggable foundation blocks for building distributed apps.</Description>
6+
<Description>Dynamic Lucene-style query support for Entity Framework and Elasticsearch. Enable powerful user-driven search queries in your .NET applications.</Description>
77
<PackageProjectUrl>https://github.com/FoundatioFx/Foundatio.LuceneQuery</PackageProjectUrl>
88
<PackageReleaseNotes>https://github.com/FoundatioFx/Foundatio.LuceneQuery/releases</PackageReleaseNotes>
9-
<PackageTags>Lucene;Query;Parser;AST;Entity Framework;LINQ;Search</PackageTags>
9+
<PackageTags>Lucene;Query;Parser;Search;EntityFramework;LINQ;Elasticsearch;Dynamic;Filtering</PackageTags>
1010
<MinVerSkip Condition="'$(Configuration)' == 'Debug'">true</MinVerSkip>
1111
<MinVerTagPrefix>v</MinVerTagPrefix>
1212

‎src/Foundatio.LuceneQueryParser.EntityFramework/Foundatio.LuceneQueryParser.EntityFramework.csproj‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<ItemGroup>
4+
<ProjectReference Include="..\Foundatio.LuceneQuery\Foundatio.LuceneQuery.csproj" />
5+
</ItemGroup>
6+
7+
<ItemGroup>
8+
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
9+
</ItemGroup>
10+
11+
</Project>

‎tests/Foundatio.LuceneQueryParser.EntityFramework.Tests/Foundatio.LuceneQueryParser.EntityFramework.Tests.csproj‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<ItemGroup>
4+
<PackageReference Include="Microsoft.Data.SqlClient" Version="6.0.2" />
5+
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
6+
<PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="9.0.0" />
7+
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
8+
<PackageReference Include="Testcontainers.MsSql" Version="4.4.0" />
9+
</ItemGroup>
10+
11+
<ItemGroup>
12+
<ProjectReference Include="..\..\src\Foundatio.LuceneQuery.EntityFramework\Foundatio.LuceneQuery.EntityFramework.csproj" />
13+
</ItemGroup>
14+
15+
</Project>

‎tests/Foundatio.LuceneQueryParser.Tests/Foundatio.LuceneQueryParser.Tests.csproj‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<ItemGroup>
4+
<ProjectReference Include="..\..\src\Foundatio.LuceneQuery\Foundatio.LuceneQuery.csproj" />
5+
</ItemGroup>
6+
7+
</Project>

0 commit comments

Comments
 (0)