Magic IndexedDB - Blazor Introduction
Author: Lance Wright II
Published: March 25, 2025
This is the introduction to utilizing Magic IndexedDB in Blazor.
Introduction to LINQ to IndexedDB in Blazor
1. Getting Started
Before we dive into queries, let's first set up Magic IndexedDB in your Blazor pages.
🔹 Add Magic IndexedDB to `_Imports.razor`
To avoid writing @using Magic.IndexedDb on every page, add it to your `_Imports.razor`:
@using Magic.IndexedDb
🔹 Inject Magic IndexedDB Into Your Pages
In any Blazor page or component where you want to use Magic IndexedDB, inject the service at the top:
@inject IMagicIndexedDb _MagicDb
Boom! You're plugged in and ready to go! 🎉
2. Initializing a Query
Now that you've injected _MagicDb, you can start querying IndexedDB! There are four ways to initialize a query:
✅ 1. Default Database Query
IMagicQuery<Person> personQuery = await _MagicDb.Query<Person>();
Targets the default database associated with Person.
If your Person table is linked to a single database, this is the best way to query it.
✅ 2. Querying an Assigned Database (Strongly Typed)
IMagicQuery<Person> employeeDbQuery = await _MagicDb.Query<Person>(x => x.Databases.Client);
Explicitly specifies which database to query.
Person is configured to exist in the Client database, so this is a safe and recommended approach.
⚠️ 3. Querying an Unassigned Database (Not Recommended)
IMagicQuery<Person> animalDbQuery = await _MagicDb.Query<Person>(IndexDbContext.Animal);
Person does not belong to the Animal database.
Magic IndexedDB allows this for flexibility, but it's discouraged.
Why? It bypasses safety checks and may require manual migrations.
🚨 4. Full Override Query (Strongly Discouraged)
IMagicQuery<Person> unassignedDbQuery = await _MagicDb.QueryOverride<Person>("DbName", "SchemaName");
Completely overrides database and schema restrictions.
Magic IndexedDB cannot protect you if you use this.
DO NOT DO THIS unless you absolutely know what you're doing.
❌ Avoid unassigned queries and full overrides unless necessary.
- They break the built-in migration system.
- They require manual fixes when schema updates occur.
- You lose all built-in protection mechanisms.
Which One Should You Use?
| Query Type | Safety Level | When to Use? |
|---|---|---|
await _MagicDb.Query<Person>(); |
✅ Safe | When Person has one default database. |
await _MagicDb.Query<Person>(x => x.Databases.Client); |
✅ Safe | When Person has multiple valid databases. |
await _MagicDb.Query<Person>(IndexDbContext.Animal); |
⚠️ Risky | When Person is not part of the specified database. |
await _MagicDb.QueryOverride<Person>("DbName", "SchemaName"); |
🚨 Dangerous | Only for advanced niche use cases. |
3. Basic CRUD Operations
Now that you know how to query, let's look at basic IndexedDB operations.
🔹 Adding Data
await personQuery.AddAsync(new Person { Name = "John Doe", Age = 30 });
🔹 Adding Multiple Records (Batch Insert)
List<Person> persons = new List<Person>
{
new Person { Name = "Alice", Age = 25 },
new Person { Name = "Bob", Age = 28 }
};
await personQuery.AddRangeAsync(persons);
🔹 Updating Data
var person = new Person { Name = "John Doe", Age = 31 };
await personQuery.UpdateAsync(person);
🔹 Updating Multiple Records
await personQuery.UpdateRangeAsync(persons);
🔹 Deleting Data
await personQuery.DeleteAsync(person);
🔹 Deleting Multiple Records
await personQuery.DeleteRangeAsync(persons);
🚀 Bulk Clearing a Table
await personQuery.ClearTable();
Deletes all data inside the table instantly.
Use with caution! 🔥
Using LINQ to IndexedDB – Query Syntax & Best Practices
1. Supported Query Operations
Magic IndexedDB fully supports LINQ-style queries, enabling powerful data retrieval and filtering while enforcing best practices to ensure optimal IndexedDB performance.
There are two primary query operations in Magic IndexedDB:
1️⃣ .Where(x => YourPredicate) → Optimized for Indexed Queries
2️⃣ .Cursor(x => YourPredicate) → Meta-data Driven Cursor Queries
Before we dive in, there's something critical you must know:
🚨 IndexedDB Has a Backwards Take/Skip Order!
In every language and database system, Skip() is always before Take().
✅ Example in SQL:
SELECT * FROM People ORDER BY Age LIMIT 10 OFFSET 5;
Here, OFFSET 5 (skip) happens before LIMIT 10 (take).
🚨 In IndexedDB, this is reversed.
If you call Skip(5).Take(10), only Skip(5) will apply
If you call Take(10).Skip(5), it works correctly
🔥 Magic IndexedDB handles this for you—but you must always write Take() before Skip() to avoid unexpected behavior.
This is also an enforced behavior by the interfaces to protect you. As the interfaces on the query won't allow you to append any Take or TakeLast after a Skip.
2. Using `.Where()` for Optimized Queries
The .Where() method translates LINQ expressions into the most efficient IndexedDB queries possible.
Multiple .Where() statements can be chained together.
✅ Basic `.Where()` Query
await personQuery.Where(x => x.Age > 30)
.Where(x => x.TestInt == 9 || x.Name.StartsWith("C", StringComparison.OrdinalIgnoreCase))
.ToListAsync();
Multiple .Where() clauses are supported.
Deferred execution works identically to LINQ to SQL.
Queries execute with ToListAsync() or AsAsyncEnumerable().
🔹 Streaming Results with `AsAsyncEnumerable()`
await foreach (var person in personQuery.Where(x => x.Age > 30).AsAsyncEnumerable())
{
Console.WriteLine($"Name: {person.Name}");
}
Yields results as they come in.
Reduces memory usage when processing large datasets.
Enforces unique ID consistency across results.
🚀 Magic IndexedDB’s custom-built interop layer enables real-time yielding.
However, note that yielding incurs additional serialization costs, making bulk returns faster.
3. Query Execution Model – Understanding Indexed vs. Cursor Queries
Magic IndexedDB automatically categorizes queries into one of three optimized execution types:
✅ Indexed Queries
Fastest queries.
Utilize IndexedDB’s built-in indexing.
Example:
await personQuery.Where(x => x.Name == "Alice").ToListAsync();
Since Name has an index, it fires an Indexed Query.
⚡ Combined Indexed Queries
Utilizes multiple indexes together for efficient searching.
More powerful than standard IndexedDB queries.
Example:
await personQuery.Where(x => x.Age > 30 && x.TestInt == 9).ToListAsync();
If both Age and TestInt are indexed, this is an optimized combined indexed query.
🛑 Cursor-Based Queries (Meta-Data Driven)
Slower, but allows for more complex filtering.
Keeps only meta-data in memory until the exact desired result is known.
Example:
await personQuery.Where(x => x.Name.Contains("bo", StringComparison.OrdinalIgnoreCase)).ToListAsync();
Since Contains() is not natively indexed, a cursor query fires instead.
🔹 The more your query relies on cursors, the slower it will be.
To optimize performance, ensure your tables have proper indexes!
4. Query Interface Enforcements & Best Practices
To prevent you from accidentally breaking IndexedDB optimizations, Magic IndexedDB enforces best practices using interfaces that restrict unsafe query combinations.
Query Flow – How Queries Are Structured
public interface IMagicQuery<T> : IMagicExecute<T> where T : class
This enforces safe LINQ structures.
Query Staging – Ensuring IndexedDB-Compatible Queries
public interface IMagicQueryStaging<T> : IMagicExecute<T> where T : class
{
IMagicQueryStaging<T> Where(Expression<Func<T, bool>> predicate);
IMagicQueryPaginationTake<T> Take(int amount);
IMagicQueryFinal<T> Skip(int amount);
IMagicQueryOrderable<T> OrderBy(Expression<Func<T, object>> predicate);
}
Once you call .Skip() or .Take(), further filtering must be done in memory.
Order operations do not guarantee IndexedDB-native ordering.
Final Query Stage – No More IndexedDB Execution Allowed
public interface IMagicQueryFinal<T> : IMagicExecute<T> where T : class
{
Task<IEnumerable<T>> WhereAsync(Expression<Func<T, bool>> predicate);
}
Once you reach this stage, all further filtering happens in memory.
🚀 Magic IndexedDB’s system ensures that your queries are optimized for IndexedDB execution wherever possible.
It prevents you from making mistakes that would force everything into memory unnecessarily.
5. Using `.Cursor()` for Full Cursor-Based Queries
If you explicitly want to use a cursor query, use .Cursor() instead of .Where().
✅ Cursor Query Example
await personQuery.Cursor(x => x.Name == "Zack").ToListAsync();
Forces all operations into a cursor query.
Allows deeper filtering than Indexed Queries.
Can still use .OrderBy(), .Take(), .Skip(), etc.
Cursor Query Interface
public interface IMagicCursor<T> : IMagicExecute<T> where T : class
{
IMagicCursor<T> Cursor(Expression<Func<T, bool>> predicate);
IMagicCursorStage<T> Take(int amount);
IMagicCursorSkip<T> Skip(int amount);
}
Cursor queries unlock more capabilities but sacrifice performance.
🚨 Only use .Cursor() when you know an indexed query won’t work!
Otherwise, stick with .Where() for better performance.
6. Supported LINQ Operations
Magic IndexedDB supports a rich LINQ feature set, including:
✅ Comparison Operators
await personQuery.Where(x => x.Age > 30).ToListAsync();
await personQuery.Where(x => x.Name == "Alice").ToListAsync();
✅ String Operations
await personQuery.Where(x => x.Name.StartsWith("C", StringComparison.OrdinalIgnoreCase)).ToListAsync();
await personQuery.Where(x => x.Name.Contains("bo", StringComparison.OrdinalIgnoreCase)).ToListAsync();
await personQuery.Where(x => x.Name.Equals("John", StringComparison.OrdinalIgnoreCase)).ToListAsync();
✅ Deeply Nested `||` Conditions
await personQuery.Where(p =>
(
(p.TestInt == 9 || p.TestInt == 3 || p.TestInt == 7) &&
(
(p.Name == "Luna" || p.Name == "Jerry" || p.Name == "Jamie") ||
(p._Age >= 35 && p._Age <= 40) ||
(p.Name == "Zane" && p._Age > 45)
) &&
(p._Age < 30 || p._Age > 50 || p._Age == 35)
)).ToListAsync();
IndexedDB can’t handle this.
Magic IndexedDB eats it for breakfast. 😎
The universal layer flattens, optimizes, and rewires your predicates without reflection or runtime overhead.
Yes, it’s real. No, it’s not lazy. This is hyper optimized.
You write clean logic — Magic IndexedDB handles the madness.
Shouldn't this take 720+ operations when flattened?
❓ Mini FAQ — Wait, What?!
🧮 Shouldn’t this take like 720+ operations when flattened?
Nope. Magic’s partitioning engine actually collapses this example into just 1 or 2 operations.
🔍 But you can’t use Indexed queries with logic like this, right?
Why do you keep thinking there's limitations? This is Magic!
If your schema supports the fields, Magic still uses Indexed queries.
I'm a "make my cake and eat it too" kind of guy — and Magic IndexedDB is the entire damn bakery.
Executing Queries Directly Without `.Where()` or `.Cursor()`
Instead of using .Where() or .Cursor(), you can execute queries directly on the query itself, just like LINQ to SQL.
🔹 Retrieving All Records
await _MagicDb.Query<Person>().ToListAsync();
Fetches the entire table, equivalent to SELECT * FROM Person;.
🔹 Ordering & Pagination
await _MagicDb.Query<Person>().OrderBy(x => x.Age).Take(5).ToListAsync();
await _MagicDb.Query<Person>().OrderByDescending(x => x.Id).Skip(10).Take(5).ToListAsync();
Supports ordering, skipping, and taking records just like SQL.
Reminder: IndexedDB requires Take() before Skip().
🔹 Fetching a Single Record
await _MagicDb.Query<Person>().FirstOrDefaultAsync();
await _MagicDb.Query<Person>().LastOrDefaultAsync();
Retrieves the first or last record efficiently.
This allows for simple, SQL-like querying while leveraging IndexedDB optimizations behind the scenes! 🚀
LINQ to IndexedDB – Full Querying Guide & Operations
1. Understanding Query Operations in Magic IndexedDB
Magic IndexedDB provides a true LINQ to IndexedDB experience, translating LINQ expressions into optimized IndexedDB queries.
There are two primary querying methods:
| Query Method | Purpose | Best For |
|---|---|---|
.Where(x => Predicate) |
Optimized IndexedDB Queries | Fast queries using indexed fields |
.Cursor(x => Predicate) |
Full Cursor Querying | Advanced filtering when indexing isn’t possible |
TL;DR: Always prefer .Where() for performance. Use .Cursor() only when needed.
2. Query Execution – IndexedDB vs. Cursor Queries
Before diving into syntax, it's important to understand how queries execute.
IndexedDB only supports certain query patterns efficiently.
Magic IndexedDB automatically categorizes your query into:
✅ Indexed Query
⚡ Combined Indexed Query
🛑 Cursor Query (Meta-data driven)
Each || condition is broken down into independent queries.
If an && operation cannot be fully indexed, that entire && block becomes a Cursor Query.
Using StringComparison.OrdinalIgnoreCase forces a cursor.
Read the LINQ to IndexedDB Fundamentals to understand how your queries are optimized!
3. Supported LINQ Operations
Magic IndexedDB supports a rich set of LINQ expressions for querying your data.
✅ Comparison Operators
await personQuery.Where(x => x.Age > 30).ToListAsync();
await personQuery.Where(x => x.Name == "Alice").ToListAsync();
✅ String Operations
await personQuery.Where(x => x.Name.StartsWith("C", StringComparison.OrdinalIgnoreCase)).ToListAsync();
await personQuery.Where(x => x.Name.Contains("bo", StringComparison.OrdinalIgnoreCase)).ToListAsync();
await personQuery.Where(x => x.Name.Equals("John", StringComparison.OrdinalIgnoreCase)).ToListAsync();
⚠ Using StringComparison.OrdinalIgnoreCase forces a cursor query.
Use indexed fields whenever possible!
✅ Deeply Nested `||` Conditions
await personQuery.Where(p =>
(
(p.TestInt == 9 || p.TestInt == 3 || p.TestInt == 7)
&&
(
(p.Name == "Luna" || p.Name == "Jerry" || p.Name == "Jamie")
|| (p._Age >= 35 && p._Age <= 40)
|| (p.Name == "Zane" && p._Age > 45)
)
&&
(
p._Age < 30 || p._Age > 50 || p._Age == 35
)
)).ToListAsync();
IndexedDB does NOT support deeply nested || operations by default.
Magic IndexedDB flattens and optimizes them for you.
4. Query Operations – Order of Execution
The following table defines the operations available and how they interact.
🔹 Indexed Query (.Where()) Execution Order
| Operation | Allowed Before | Allowed After | Notes |
|---|---|---|---|
.Where() |
Start | .Where(), .OrderBy(), .ToListAsync() |
Supports indexing optimizations. |
.OrderBy() && order by descending |
.Where() |
.Take(), .Skip(), .ToListAsync() |
Ordering is NOT guaranteed in IndexedDB. Must reapply after query. |
.Take() |
.Where(), .OrderBy() |
.Skip(), .ToListAsync() |
Must be before .Skip() in IndexedDB. |
.Skip() |
.Take() |
.ToListAsync() |
Skipping before taking ignores take! |
.FirstOrDefaultAsync() |
.Where() |
End | Returns first matching record. |
.LastOrDefaultAsync() |
.Where() |
End | Returns last matching record. |
🔹 Cursor Query (.Cursor()) Execution Order
| Operation | Allowed Before | Allowed After | Notes |
|---|---|---|---|
.Cursor() |
Start | .OrderBy(), .Take(), .Skip(), .ToListAsync() |
Allows full flexibility but is slower. |
.OrderBy() |
.Cursor() |
.Take(), .Skip(), .ToListAsync() |
Order will not be enforced at IndexedDB level. |
.TakeLast() |
.OrderBy() |
.ToListAsync() |
Forces in-memory filtering. |
.Skip() |
.Take() |
.ToListAsync() |
Always apply .Take() before .Skip(). |
.FirstOrDefaultAsync() |
.Cursor() |
End | Returns first matching record. |
.LastOrDefaultAsync() |
.Cursor() |
End | Returns last matching record. |
🚨 Once you use .Skip(), .Take(), .OrderBy(), filtering becomes memory-based!
IndexedDB does not allow additional .Where() operations after these.
📌 Supported Query Operators
| Operator (C# / LINQ Style) | IndexedDB Optimized? |
|---|---|
== |
✅ Yes |
!= |
✅ Yes |
> |
✅ Yes |
>= |
✅ Yes |
< |
✅ Yes |
<= |
✅ Yes |
.StartsWith() |
✅ Yes* (case-insensitive uses cursor) |
!x.StartsWith() |
🚫 Cursor Required |
.EndsWith() |
🚫 Cursor Required |
!x.EndsWith() |
🚫 Cursor Required |
.Contains() |
✅ Yes* (not for strings) |
!x.Contains() |
✅ Yes* (not for strings) |
.In([a, b, c]) |
✅ Yes |
.Length == X |
🚫 Cursor Required |
.Length > X / >= X / < X / <= X |
🚫 Cursor Required |
x == null |
🚫 Cursor Required |
x != null |
🚫 Cursor Required |
*Contains for non-strings — when working with arrays, the system tries to flatten the predicate to the universal language on your behalf.
🕒 Date & Time Query Support (C# Style)
| C# Expression | IndexedDB Optimized? |
|---|---|
x == DateTime(2020, 5, 1) | ✅ Yes (translated to range) |
x != DateTime(2020, 5, 1) | 🚫 Cursor Required |
x > DateTime(2023, 1, 1) | ✅ Yes |
x >= DateTime(2023, 1, 1) | ✅ Yes |
x < DateTime(2023, 1, 1) | ✅ Yes |
x <= DateTime(2023, 1, 1) | ✅ Yes |
x.Date == new DateTime(2023, 10, 15) | ✅ Yes (translated to range) |
x.Year == 2023 | ✅ Yes |
x.Year != 2023 | 🚫 Cursor Required |
x.Year > 2022 | ✅ Yes |
x.Year >= 2023 | ✅ Yes |
x.Year < 2024 | ✅ Yes |
x.Year <= 2023 | ✅ Yes |
x.Month == 7 | 🚫 Cursor Required |
x.Month != 12 | 🚫 Cursor Required |
x.Month > 6 | 🚫 Cursor Required |
x.Month >= 1 | 🚫 Cursor Required |
x.Month < 12 | 🚫 Cursor Required |
x.Month <= 7 | 🚫 Cursor Required |
x.Day == 4 | 🚫 Cursor Required |
x.Day != 5 | 🚫 Cursor Required |
x.Day > 2 | 🚫 Cursor Required |
x.Day >= 10 | 🚫 Cursor Required |
x.Day < 20 | 🚫 Cursor Required |
x.Day <= 15 | 🚫 Cursor Required |
x.DayOfWeek == DayOfWeek.Monday | 🚫 Cursor Required |
x.DayOfWeek != DayOfWeek.Friday | 🚫 Cursor Required |
x.DayOfWeek > DayOfWeek.Sunday | 🚫 Cursor Required |
x.DayOfWeek >= DayOfWeek.Tuesday | 🚫 Cursor Required |
x.DayOfWeek < DayOfWeek.Saturday | 🚫 Cursor Required |
x.DayOfWeek <= DayOfWeek.Monday | 🚫 Cursor Required |
x.DayOfYear == 128 | 🚫 Cursor Required |
x.DayOfYear != 129 | 🚫 Cursor Required |
x.DayOfYear > 50 | 🚫 Cursor Required |
x.DayOfYear >= 100 | 🚫 Cursor Required |
x.DayOfYear < 200 | 🚫 Cursor Required |
x.DayOfYear <= 365 | 🚫 Cursor Required |
✅ BONUS: Nullable Support
x.DateOfBirth.Value (nullable structs)
Automatic .Value stripping where safe
Error-handling for invalid usage like x.DateOfBirth.Value (without member access)
💡 Pro Tip
Operations like .Date, .Year, .Month, .Day, .DayOfWeek, and .DayOfYear are all internally optimized and recognized as special operations — no reflection, no guesswork, no slowdowns.
This is next-gen IndexedDB querying.
🔎 Type-Based Queries
| Operator | IndexedDB Optimized? |
|---|---|
x is type of int/number | 🚫 Cursor Required |
x is type of string | 🚫 Cursor Required |
typeof x === "number" | 🚫 Cursor Required |
typeof x === "string" | 🚫 Cursor Required |
x is DateTime / Date | 🚫 Cursor Required |
x is Array | 🚫 Cursor Required |
x is Object | 🚫 Cursor Required |
x is Blob | 🚫 Cursor Required |
x is ArrayBuffer | 🚫 Cursor Required |
x is File | 🚫 Cursor Required |
*Type of both equals and not equals supported.
The system automatically detects what can or cannot be converted to a JS type since IndexedDB is JavaScript-based. So type checking is not as strict as C#.
5. Cursor Queries – Unlocking Full IndexedDB Power
A .Cursor() query forces everything into a cursor-based scan, removing restrictions but also removing optimizations.
✅ Cursor Query Example
await personQuery.Cursor(x => x.Name == "Zack").ToListAsync();
Forces all operations into a cursor query.
Unlocks .TakeLast(), .Skip(), and .OrderBy().
Can be combined with .Where(), but will convert entire query into a cursor.
6. Query Interface Pathways
The following flowchart defines the order in which query operations are enforced.
🔹 Query Flowchart
Start → Where() → OrderBy() → Take() → Skip() → Execution (.ToListAsync())
↘ Cursor() → TakeLast() → Execution
🔥 Magic IndexedDB enforces these rules at the interface level!
You can’t accidentally write non-performant IndexedDB queries.
7. Full Query Examples
// Basic WHERE statement with optimized indexing
await personQuery.Where(x => x.Age > 30).ToListAsync();
// WHERE with OR conditions (flattened optimization)
await personQuery.Where(x => (x.Age > 40 && x.TestInt == 9) || x.Name.Contains("bo")).ToListAsync();
// ORDER BY, TAKE, and SKIP (Indexed)
await personQuery.Where(x => x.Age > 30)
.OrderBy(x => x.Age)
.Take(3)
.Skip(2)
.ToListAsync();
// Cursor-based querying (Allows `.TakeLast()`)
await personQuery.Cursor(x => x.Age > 30)
.OrderBy(x => x.Age)
.TakeLast(2)
.ToListAsync();
// FirstOrDefault and LastOrDefault
await personQuery.OrderBy(x => x.Age).FirstOrDefaultAsync();
await personQuery.OrderBy(x => x.Age).LastOrDefaultAsync();
Quick "good to know"
Use Contains for both strings and arrays:
int[] myArray = { 38, 39 };
await personQuery.Where(x => myArray.Contains(x._Age));
This works for arrays in both directions.
.Cursor(x => Your_Predicate) allows different paths than .Where and supports current and future planned operations like .Min, .Max, and .Select.
Biggest TLDR of why .Cursor is different from .Where is that when using .Cursor, there is no way an indexed query will fire. The .Where doesn’t guarantee that an indexed query fires, but it means it’s not impossible.
Utilizing capabilities like x.Item == null or x.Item != null is fully supported.
But it’s important to remember this translation checks if it’s directly set to null, an empty string (if it's a string), or an undefined column.
Avoid querying with x.Item.Value on nullable variables when possible.
It can throw the serializer off. For supported appended operations like .Length, .Year, .GetDay, .GetDayOfWeek, .GetDayOfYear, these and a few others are the only times you should use the .Value suffix. This is the only way in C# to allow access to such properties on nullable types (e.g., x.Item.Value.Length).
What You Need To Know
Before you go off and start using the library. This documentation was for sure the bulkiest, but everything else is much smaller! You've done it, congrats! But there's still really critical information you must be aware of. Before you venture forth, I suggest reading the following in order:
Read the Utility Guide To learn about the additional Syntax and capabilities.
How Ordering Works To learn about how and why the ordering is different with LINQ to IndexedDB.
Installation Instructions To learn about how to setup your project.
Migrations Guide To learn about how to setup the migrations for future updates.
Read the LINQ to IndexedDB Fundamentals to master IndexedDB optimizations! 🚀
It's not as much as you'd think, I promise! It's worth knowing and understanding.
