전역 쿼리 필터Global Query Filters

참고

이 기능은 EF Core 2.0에서 도입되었습니다.This feature was introduced in EF Core 2.0.

전역 쿼리 필터는 메타데이터 모델(일반적으로 OnModelCreating)의 엔터티 형식에 적용되는 LINQ 쿼리 조건자입니다.Global query filters are LINQ query predicates applied to Entity Types in the metadata model (usually in OnModelCreating). 쿼리 조건자는 일반적으로 LINQ Where 쿼리 연산자에 전달되는 부울 식입니다.A query predicate is a boolean expression typically passed to the LINQ Where query operator. EF Core는 이러한 필터를 해당 엔터티 형식과 관련된 모든 LINQ 쿼리에 자동으로 적용합니다.EF Core applies such filters automatically to any LINQ queries involving those Entity Types. EF Core는 Include 또는 탐색 속성을 사용하여 간접적으로 참조되는 엔터티 형식에도 해당 필터를 적용합니다.EF Core also applies them to Entity Types, referenced indirectly through use of Include or navigation property. 이 기능의 몇 가지 일반적인 용도는 다음과 같습니다.Some common applications of this feature are:

  • 일시 삭제 - 엔터티 형식이 IsDeleted 속성을 정의합니다.Soft delete - An Entity Type defines an IsDeleted property.
  • 다중 테넌트 - 엔터티 형식이 TenantId 속성을 정의합니다.Multi-tenancy - An Entity Type defines a TenantId property.

예제Example

다음 예제에서는 전역 쿼리 필터를 사용하여 간단한 블로그 모델에서 다중 테넌트 및 일시 삭제 쿼리 동작을 구현하는 방법을 보여 줍니다.The following example shows how to use Global Query Filters to implement multi-tenancy and soft-delete query behaviors in a simple blogging model.

GitHub에서 다중 테넌트 샘플탐색을 사용한 샘플을 볼 수 있습니다.You can view a multi-tenancy sample and samples using navigations on GitHub.

먼저 엔터티를 정의합니다.First, define the entities:

public class Blog
{
    private string _tenantId;

    public int BlogId { get; set; }
    public string Name { get; set; }
    public string Url { get; set; }

    public List<Post> Posts { get; set; }
}

public class Post
{
    public int PostId { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public bool IsDeleted { get; set; }

    public Blog Blog { get; set; }
}

블로그 엔터티에서 tenantId 필드의 선언을 확인하세요.Note the declaration of a tenantId field on the Blog entity. 이 필드는 각 Blog 인스턴스를 특정 테넌트와 연결하는 데 사용됩니다.This field will be used to associate each Blog instance with a specific tenant. 또한 IsDeleted 속성은 Post 엔터티 형식에 정의되어 있습니다.Also defined is an IsDeleted property on the Post entity type. 이 속성은 Post 인스턴스가 “일시 삭제”되었는지 여부를 추적하는 데 사용됩니다.This property is used to keep track of whether a Post instance has been "soft-deleted". 즉, 기본 데이터를 물리적으로 제거하지 않아도 인스턴스가 삭제된 것으로 표시됩니다.That is, the instance is marked as deleted without physically removing the underlying data.

다음으로, HasQueryFilter API를 사용하여 _OnModelCreating_에서 쿼리 필터를 구성합니다.Next, configure the query filters in OnModelCreating using the HasQueryFilter API.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>().Property<string>("_tenantId").HasColumnName("TenantId");

    // Configure entity filters
    modelBuilder.Entity<Blog>().HasQueryFilter(b => EF.Property<string>(b, "_tenantId") == _tenantId);
    modelBuilder.Entity<Post>().HasQueryFilter(p => !p.IsDeleted);
}

이제 HasQueryFilter 호출에 전달된 조건자 식이 해당 형식에 대한 모든 LINQ 쿼리에 자동으로 적용됩니다.The predicate expressions passed to the HasQueryFilter calls will now automatically be applied to any LINQ queries for those types.

DbContext 인스턴스 수준 필드를 사용합니다. _tenantId는 현재 테넌트를 설정하는 데 사용됩니다.Note the use of a DbContext instance level field: _tenantId used to set the current tenant. 모델 수준 필터는 올바른 컨텍스트 인스턴스(즉, 쿼리를 실행하는 인스턴스)의 값을 사용합니다.Model-level filters will use the value from the correct context instance (that is, the instance that is executing the query).

참고

현재 동일한 엔터티에 여러 개의 쿼리 필터를 정의할 수 없습니다. 마지막 필터만 적용됩니다.It is currently not possible to define multiple query filters on the same entity - only the last one will be applied. 그러나 논리 AND 연산자(C#의 &&)를 사용하여 여러 조건으로 단일 필터를 정의할 수 있습니다.However, you can define a single filter with multiple conditions using the logical AND operator (&& in C#).

탐색 사용Use of navigations

탐색은 전역 쿼리 필터를 정의하는 데에도 사용할 수 있습니다.You can also use navigations in defining global query filters. 쿼리 필터에 탐색을 사용하면 쿼리 필터가 재귀적으로 적용됩니다.Using navigations in query filter will cause query filters to be applied recursively. EF Core는 쿼리 필터에 사용되는 탐색을 확장할 때, 참조된 엔터티에 정의되어 있는 쿼리 필터도 적용합니다.When EF Core expands navigations used in query filters, it will also apply query filters defined on referenced entities.

참고

현재 EF Core는 전역 쿼리 필터 정의에서 주기를 검색하지 않으므로 정의할 때 주의해야 합니다.Currently EF Core does not detect cycles in global query filter definitions, so you should be careful when defining them. 잘못 지정하면 쿼리를 변환하는 동안 무한 루프가 발생할 수 있습니다.If specified incorrectly, cycles could lead to infinite loops during query translation.

필수 탐색을 사용하여 쿼리 필터를 통해 엔터티 액세스Accessing entity with query filter using required navigation

주의

전역 쿼리 필터가 정의된 엔터티에 액세스하는 데 필수 탐색을 사용하면 예기치 않은 결과가 발생할 수 있습니다.Using required navigation to access entity which has global query filter defined may lead to unexpected results.

필수 탐색을 수행하려면 관련 엔터티가 항상 표시되어야 합니다.Required navigation expects the related entity to always be present. 필요한 관련 엔터티가 쿼리 필터에 의해 필터링되면 부모 엔터티도 결과에 포함되지 않습니다.If necessary related entity is filtered out by the query filter, the parent entity wouldn't be in result either. 따라서 결과에 나타나는 요소가 예상보다 적을 수 있습니다.So you may get fewer elements than expected in result.

문제를 설명하기 위해 위에 지정된 BlogPost 엔터티와 다음 OnModelCreating 메서드를 사용할 수 있습니다.To illustrate the problem, we can use the Blog and Post entities specified above and the following OnModelCreating method:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>().HasMany(b => b.Posts).WithOne(p => p.Blog).IsRequired();
    modelBuilder.Entity<Blog>().HasQueryFilter(b => b.Url.Contains("fish"));
}

모델은 다음 데이터를 사용하여 시드될 수 있습니다.The model can be seeded with the following data:

db.Blogs.Add(
    new Blog
    {
        Url = "http://sample.com/blogs/fish",
        Posts = new List<Post>
        {
            new Post { Title = "Fish care 101" },
            new Post { Title = "Caring for tropical fish" },
            new Post { Title = "Types of ornamental fish" }
        }
    });

db.Blogs.Add(
    new Blog
    {
        Url = "http://sample.com/blogs/cats",
        Posts = new List<Post>
        {
            new Post { Title = "Cat care 101" },
            new Post { Title = "Caring for tropical cats" },
            new Post { Title = "Types of ornamental cats" }
        }
    });

다음 두 개의 쿼리를 실행하는 경우 이 문제를 관찰할 수 있습니다.The problem can be observed when executing two queries:

var allPosts = db.Posts.ToList();
var allPostsWithBlogsIncluded = db.Posts.Include(p => p.Blog).ToList();

위 설정을 사용하면 첫 번째 쿼리는 6개 Post를 모두 반환하지만 두 번째 쿼리는 3개만 반환합니다.With above setup, the first query returns all 6 Posts, however the second query only returns 3. 이 불일치는 두 번째 쿼리의 Include 메서드가 관련 Blog 엔터티를 로드하기 때문에 발생합니다.This mismatch happens because Include method in the second query loads the related Blog entities. BlogPost 간에 탐색이 필요하므로 EF Core는 쿼리를 생성할 때 INNER JOIN을 사용합니다.Since the navigation between Blog and Post is required, EF Core uses INNER JOIN when constructing the query:

SELECT [p].[PostId], [p].[BlogId], [p].[Content], [p].[IsDeleted], [p].[Title], [t].[BlogId], [t].[Name], [t].[Url]
FROM [Post] AS [p]
INNER JOIN (
    SELECT [b].[BlogId], [b].[Name], [b].[Url]
    FROM [Blogs] AS [b]
    WHERE CHARINDEX(N'fish', [b].[Url]) > 0
) AS [t] ON [p].[BlogId] = [t].[BlogId]

INNER JOIN를 사용하면 전역 쿼리 필터에 의해 관련 Blog가 제거된 모든 Post가 필터링으로 제외됩니다.Use of the INNER JOIN filters out all Posts whose related Blogs have been removed by a global query filter.

이 문제는 필수가 아닌 선택적 탐색을 사용하여 해결할 수 있습니다.It can be addressed by using optional navigation instead of required. 이렇게 하면 첫 번째 쿼리는 이전과 동일하게 유지되지만 두 번째 쿼리는 이제 LEFT JOIN을 생성하고 6개 결과를 반환합니다.This way the first query stays the same as before, however the second query will now generate LEFT JOIN and return 6 results.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>().HasMany(b => b.Posts).WithOne(p => p.Blog).IsRequired(false);
    modelBuilder.Entity<Blog>().HasQueryFilter(b => b.Url.Contains("fish"));
}

대체 방법은 BlogPost 엔터티 둘 다에서 일관된 필터를 지정하는 것입니다.Alternative approach is to specify consistent filters on both Blog and Post entities. 이렇게 하면 일치하는 필터가 BlogPost 둘 다에 적용됩니다.This way matching filters are applied to both Blog and Post. 예기치 않은 상태로 종료될 수 있는 Post가 제거되며 두 쿼리가 모두 3개 결과를 반환합니다.Posts that could end up in unexpected state are removed and both queries return 3 results.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>().HasMany(b => b.Posts).WithOne(p => p.Blog).IsRequired();
    modelBuilder.Entity<Blog>().HasQueryFilter(b => b.Url.Contains("fish"));
    modelBuilder.Entity<Post>().HasQueryFilter(p => p.Blog.Url.Contains("fish"));
}

필터 사용 안 함Disabling Filters

IgnoreQueryFilters() 연산자를 사용하여 개별 LINQ 쿼리에 대해 필터를 사용하지 않도록 설정할 수 있습니다.Filters may be disabled for individual LINQ queries by using the IgnoreQueryFilters() operator.

blogs = db.Blogs
    .Include(b => b.Posts)
    .IgnoreQueryFilters()
    .ToList();

제한 사항Limitations

전역 쿼리 필터에는 다음 제한 사항이 있습니다.Global query filters have the following limitations:

  • 상속 계층 구조의 루트 엔터티 형식에 대해서만 필터를 정의할 수 있습니다.Filters can only be defined for the root Entity Type of an inheritance hierarchy.