A query is a set of instructions that describes what data to retrieve from a given data source (or sources) and what shape and organization the returned data should have. A query is distinct from the results that it produces.

Generally, the source data is organized logically as a sequence of elements of the same kind. A SQL database table contains a sequence of rows. Similarly, an ADO.NET DataTable contains a sequence of DataRow objects. In an XML file, there is a "sequence" of XML elements (although these are organized hierarchically in a tree structure). An in-memory collection contains a sequence of objects.

From an application's viewpoint, the specific type and structure of the original source data is not important. The application always sees the source data as an IEnumerable<(Of <(T>)>) or IQueryable<(Of <(T>)>) collection. In LINQ to XML, the source data is made visible as an IEnumerable<XElement>. In LINQ to DataSet, it is an IEnumerable<DataRow>. In LINQ to SQL, it is an IEnumerable or IQueryable of whatever custom objects you have defined to represent the data in the SQL table.

Given this source sequence, a query may do one of three things:

• Retrieve a subset of the elements to produce a new sequence without modifying the individual elements. The query may then sort or group the returned sequence in various ways, as shown in the following example (assume scores is an int[]):

  C#

  IEnumerable<> highScoresQuery =
       score  scores
       score > 80
       score 
       score;
  
  

• Retrieve a sequence of elements as in the previous example but transform them to a new type of object. For example, a query may retrieve only the last names from certain customer records in a data source. Or it may retrieve the complete record and then use it to construct another in-memory object type or even XML data before generating the final result sequence. The following example shows a transform from an int to a string. Note the new type of highScoresQuery.

  C#

  IEnumerable<string> highScoresQuery2 =
       score  scores
       score > 80
       score 
       String.Format(, score);
  
  

• Retrieve a singleton value about the source data, such as:

  • The number of elements that match a certain condition.

  • The element that has the greatest or least value.

  • The first element that matches a condition, or the sum of particular values in a specified set of elements. For example, the following query returns the number of scores greater than 80 from the scores integer array:

  C#

   highScoreCount =
      ( score  scores
        score > 80
        score)
       .Count();
  
  

  In the previous example, note the use of parentheses around the query expression before the call to the Count method. You can also express this by using a new variable to store the concrete result. This technique is more readable because it keeps the variable that store the query separate from the query that stores a result.

  C#

  IEnumerable<> highScoresQuery3 =
       score  scores
       score > 80
       score;
  
   scoreCount = highScoresQuery3.Count();
  
  

In the previous example, the query is executed in the call to Count, because Count must iterate over the results in order to determine the number of elements returned by highScoresQuery.

A query expression is a query expressed in query syntax. A query expression is a first-class language construct. It is just like any other expression and can be used in any context in which a C# expression is valid. A query expression consists of a set of clauses written in a declarative syntax similar to SQL or XQuery. Each clause in turn contains one or more C# expressions, and these expressions may themselves be either a query expression or contain a query expression.

A query expression must begin with a from clause and must end with a select or group clause. Between the first from clause and the last select or group clause, it can contain one or more of these optional clauses: where, orderby, join, let and even additional from clauses. You can also use the into keyword to enable the result of a join or group clause to serve as the source for additional query clauses in the same query expression.

The Query Variable

In LINQ, a query variable is any variable that stores a query instead of the results of a query. More specifically, a query variable is always an enumerable type that will produce a sequence of elements when it is iterated over in a foreach statement or a direct call to its IEnumerator.MoveNext method.

The following code example shows a simple query expression with one data source, one filtering clause, one ordering clause, and no transformation of the source elements. The select clause ends the query.

C#

  Main()
{
    
    [] scores = { 90, 71, 82, 93, 75, 82 };

    
    IEnumerable<> scoreQuery = 
         score  scores 
         score > 80 
         score  
         score; 

    
     ( testScore  scoreQuery)
    {
        Console.WriteLine(testScore);
    }                  
}

In the previous example, scoreQuery is a query variable, which is sometimes referred to as just a query. The query variable stores no actual result data, which is produced in the foreach loop. And when the foreach statement executes, the query results are not returned through the query variable scoreQuery. Rather, they are returned through the iteration variable testScore. The scoreQuery variable can be iterated in a second foreach loop. It will produce the same results as long as neither it nor the data source has been modified.

A query variable may store a query that is expressed in query syntax or method syntax, or a combination of the two. In the following examples, both queryMajorCities and queryMajorCities2 are query variables:

C#

IEnumerable<City> queryMajorCities =
     city  cities
     city.Population > 100000
     city;



IEnumerable<City> queryMajorCities2 = cities.Where(c => c.Population > 100000);

On the other hand, the following two examples show variables that are not query variables even through each is initialized with a query. They are not query variables because they store results:

C#

 highestScore =
    ( score  scores
      score)
    .Max();


IEnumerable<> scoreQuery =
     score  scores
     score;

 highScore = scoreQuery.Max();

IEnumerable<City> largeCityList =
    ( country  countries
      city  country.Cities
         city.Population > 10000
         city)
       .ToList();


IEnumerable<City> largeCityList2 =
     country  countries
      city  country.Cities
      city.Population > 10000
      city;

List<City> largeCities = largeCityList2.ToList();

Note:
In the LINQ documentation, variables that store a query have the word "query" as part of their names. Variables that store an actual result do not have "query" in their names.

For more information about the different ways to express queries, see Query Syntax versus Method Syntax (LINQ).

Explicit and Implicit Typing of Query Variables

This documentation usually provides the explicit type of the query variable in order to show the type relationship between the query variable and the select clause. However, you can also use the var keyword to instruct the compiler to infer the type of a query variable (or any other local variable) at compile time. For example, the query example that was shown previously in this topic can also be expressed by using implicit typing:

C#

var queryCities =
     city  cities
     city.Population > 100000
     city;

For more information, see Implicitly Typed Local Variables (C# Programming Guide) and Type Relationships in Query Operations (LINQ).

Starting a query expression

IEnumerable<Country> countryAreaQuery =
     country  countries
     country.Area > 500000 
     country;

IEnumerable<City> cityQuery =
     country  countries
     city  country.Cities
     city.Population > 10000
     city;

Ending a Query Expression

var queryCountryGroups =
     country  countries
     country  country.Name[0];

IEnumerable<Country> sortedQuery =
     country  countries
     country.Area
     country;

var queryNameAndPop =
     country  countries
      { Name = country.Name, Pop = country.Population };

var percentileQuery =
     country  countries
     percentile = () country.Population / 10000000
     country  percentile  countryGroup
     countryGroup.Key >= 20
     countryGroup.Key
     countryGroup;


 (var grouping  percentileQuery)
{
    Console.WriteLine(grouping.Key);
     (var country  grouping)
        Console.WriteLine(country.Name +  + country.Population);
}

Filtering, Ordering, and Joining

IEnumerable<City> queryCityPop =
     city  cities
     city.Population < 200000 && city.Population > 100000
     city;

IEnumerable<Country> querySortedCountries =
     country  countries
     country.Area > 500000, country.Population 
     country;

var categoryQuery =
     cat  categories
     prod  products  cat  prod.Category
      { Category = cat, Name = prod.Name };

string[] names = { , , ,  };
IEnumerable<string> queryFirstNames =
     name  names
     firstName = name.Split( [] { ' ' })[0]
     firstName;

 (string s  queryFirstNames)
    Console.Write(s + );

Subqueries in a Query Expression

var queryGroupMax =
     student  students
     student  student.GradeLevel  studentGroup
     
    {
        Level = studentGroup.Key,
        HighestScore =
            ( student2  studentGroup
              student2.Scores.Average())
             .Max()
    };

Concepts

Reference

Other Resources

Uma query é um conjunto de instruções que descrevem qual dado receber de um data source(ou sources) e em qual formato e organização os dados deveriam ter. Uma query é diferenciada a partir dos resultados que ela produz.

Geralmente, os dados de origem são organizados logicamente como uma sequência de elementos do mesmo tipo. Uma tabela de um banco de dados SQL contém uma sequência de linhas. Similarly, an ADO.NET DataTable contains a sequence of DataRow objects. Em um arquivo XML, existe uma "sequência" de elementos XML (apesar destes serem organizados hierarquicamente em uma estrutura de árvore). Uma coleçao na mémoria contém uma sequência de objetos.

Do ponto de vista do aplicativo, o tipo específico e a estrutura dos dados de origem original não é importante. O aplicativo sempre vê os dados de origem como um IEnumerable<(Of <(T>)>) ou IQueryable<(Of <(T>)>) coleção. Em LINQ to XML, os dados de origem são tornados Visível como um IEnumerable<XElement >. Em LINQ to DataSet, é um IEnumerable<DataRow >. Em LINQ to SQL, é um IEnumerable ou IQueryable de qualquer Personalizar objetos que você definiu para representar os dados na tabela SQL.

Dada essa seqüência de origem, uma consulta pode siga um destes três coisas:

• Recupere um subconjunto dos elementos para produzir uma Novo seqüência sem modificar os elementos individuais. A consulta pode em seguida, classificar ou agrupar a seqüência retornada em várias formas, conforme o exemplo seguinte (presuma scores é uma int[]):

  C#

  IEnumerable<> highScoresQuery =
       score  scores
       score > 80
       score 
       score;
  
  

• Recuperar uma seqüência de elementos como no exemplo anterior, mas Transformará-los para um novo tipo de objeto. Por exemplo, uma consulta pode recuperar apenas os últimos nomes de determinados registros de cliente em uma Origem de dados. Ou ele pode recuperar o registro completo e usá-lo para criar outro tipo de objeto de memória ou até mesmo dados XML antes de gerar a seqüência do resultado final. O exemplo a seguir mostra uma Transformarar de um int para um string. Anotação o novo tipo de highScoresQuery.

  C#

  IEnumerable<string> highScoresQuery2 =
       score  scores
       score > 80
       score 
       String.Format(, score);
  
  

• Recuperar um valor singleton sobre os dados de origem, tais como:

  • O número de elementos que coincidam com uma determinada condição.

  • O elemento que possui o valor maior ou menor.

  • O primeiro elemento que corresponde a uma condição ou soma de valores específicos de um conjunto especificado de elementos. Por exemplo, a seguinte consulta retorna o número de pontuação maior do que 80 da matriz de inteiro scores:

  C#

   highScoreCount =
      ( score  scores
        score > 80
        score)
       .Count();
  
  

  No exemplo anterior, Anotação o uso de parênteses em torno da expressão de consulta antes da chamada ao método Count. Você também pode expressar isso usando uma Novo variável para armazenar o resultado de concreto. Essa técnica é mais legível, pois ele mantém a variável que armazede a consulta separade da consulta que armazede um resultade.

  C#

  IEnumerable<> highScoresQuery3 =
       score  scores
       score > 80
       score;
  
   scoreCount = highScoresQuery3.Count();
  
  

No exemplo anterior, a consulta é executada na chamada para Count, porque Count deve iterar sobre os resultados em Ordem para determinar o número de elementos retornados pela highScoresQuery.

Um de expressão de consulta é uma consulta expressa na sintaxe de consulta. Uma expressão de consulta é uma Primeiro classe Idioma construir. Ele é como qualquer outra expressão e pode ser usado em qualquer contexto em que uma expressão de C# é válida. Uma expressão de consulta consiste em um conjunto das cláusulas escrito em uma sintaxe declarativa semelhante a SQL ou XQuery. Cada cláusula por sua vez contém um ou mais expressões do C# e essas expressões podem se ser uma expressão de consulta ou conter uma expressão de consulta.

Uma expressão de consulta deve começar com um cláusula from e deve terminar com umSelecionar de ou AAgruparar cláusula. Entre a Primeiro cláusula from e o último select ou group cláusula, ele pode conter um ou mais dessas cláusulas opcionais: onde, orderby, Junção, permitem e até adicionais de cláusulas. Também pode usar o na palavra-chave para habilitar o resultado de um join ou group cláusula para servir como a Origem para as cláusulas de consulta adicional na mesma expressão de consulta.

A variável de consulta

Em LINQ, uma variável de consulta é qualquer variável que armazena um de consulta em vez do de uma consulta de resultados. Mais especificamente, uma variável de consulta sempre é um tipo enumeráveis que produzirá uma seqüência de elementos quando ele é iterado em uminstrução de foreach ou uma chamada direta para o método IEnumerator.MoveNext.

O exemplo de código a seguir mostra uma expressão de consulta simples com uma fonte de dados, uma cláusula de filtragem, uma cláusula de pedido e nenhuma transformação dos elementos de origem. A cláusula select termina a consulta.

C#

  Main()
{
    
    [] scores = { 90, 71, 82, 93, 75, 82 };

    
    IEnumerable<> scoreQuery = 
         score  scores 
         score > 80 
         score  
         score; 

    
     ( testScore  scoreQuery)
    {
        Console.WriteLine(testScore);
    }                  
}

No exemplo anterior, scoreQuery é uma variável de consulta de ,que às vezes é chamado de apenas umconsulta. A variável de consulta armazena não dados resultado real, que são produzidos no loop foreach. E quando executa a instrução de foreach , os resultados da consulta não são retornados Através a variável de consulta scoreQuery. Em vez disso, eles são retornados Através a variável de iteração testScore. A variável scoreQuery pode ser iterada em um segundo loop foreach. Ela produzirá os mesmos resultados, desde que ele nem a Origem de dados foi modificada.

Uma variável de consulta pode armazenar uma consulta que é expresso na sintaxe de consulta ou sintaxe do método ou uma combinação dos dois. Os exemplos a seguir, os queryMajorCities e o queryMajorCities2 são variáveis de consulta:

C#

IEnumerable<City> queryMajorCities =
     city  cities
     city.Population > 100000
     city;



IEnumerable<City> queryMajorCities2 = cities.Where(c => c.Population > 100000);

Através outro lado, os exemplos de dois a seguir mostram variáveis que não são variáveis de consulta, mesmo em cada é iniciada com uma consulta. Eles não são variáveis de consulta porque armazenam os resultados:

C#

 highestScore =
    ( score  scores
      score)
    .Max();


IEnumerable<> scoreQuery =
     score  scores
     score;

 highScore = scoreQuery.Max();

IEnumerable<City> largeCityList =
    ( country  countries
      city  country.Cities
         city.Population > 10000
         city)
       .ToList();


IEnumerable<City> largeCityList2 =
     country  countries
      city  country.Cities
      city.Population > 10000
      city;

List<City> largeCities = largeCityList2.ToList();

Observação:
Na Documentação de LINQ, variáveis que armazenam uma consulta têm a palavra "consulta" como parte de seus nomes. Variáveis que armazenam um resultado real não é necessário "consulta" em seus nomes.

Para obter mais informações sobre as diferentes maneiras para expressar consultas, consulte Sintaxe de consulta versus sintaxe do método (LINQ).

Explícito e implícita de digitação de variáveis de consulta

Esta documentação geralmente fornece o tipo explícito da variável de consulta em Ordem para mostrar o tipo de relação entre a variável de consulta e o Selecionar cláusula. No entanto, também pode usar a palavra-chave var para instruir o compilador a inferir o tipo de uma variável de consulta (ou qualquer outra variável local) em tempo de compilação. Por exemplo, o exemplo de consulta que foi mostrado anteriormente neste tópico também pode ser expresso por meio de digitação implícita:

C#

var queryCities =
     city  cities
     city.Population > 100000
     city;

Para obter mais informações, consulte Digitada implicitamente variáveis Local (C# Guia de programação) e Relações de tipo em operações de Consulta (LINQ).

Iniciar uma expressão de consulta

IEnumerable<Country> countryAreaQuery =
     country  countries
     country.Area > 500000 
     country;

IEnumerable<City> cityQuery =
     country  countries
     city  country.Cities
     city.Population > 10000
     city;

Encerrar uma expressão de consulta

var queryCountryGroups =
     country  countries
     country  country.Name[0];

IEnumerable<Country> sortedQuery =
     country  countries
     country.Area
     country;

var queryNameAndPop =
     country  countries
      { Name = country.Name, Pop = country.Population };

var percentileQuery =
     country  countries
     percentile = () country.Population / 10000000
     country  percentile  countryGroup
     countryGroup.Key >= 20
     countryGroup.Key
     countryGroup;


 (var grouping  percentileQuery)
{
    Console.WriteLine(grouping.Key);
     (var country  grouping)
        Console.WriteLine(country.Name +  + country.Population);
}

Filtragem, classificação e ingressando em

IEnumerable<City> queryCityPop =
     city  cities
     city.Population < 200000 && city.Population > 100000
     city;

IEnumerable<Country> querySortedCountries =
     country  countries
     country.Area > 500000, country.Population 
     country;

var categoryQuery =
     cat  categories
     prod  products  cat  prod.Category
      { Category = cat, Name = prod.Name };

string[] names = { , , ,  };
IEnumerable<string> queryFirstNames =
     name  names
     firstName = name.Split( [] { ' ' })[0]
     firstName;

 (string s  queryFirstNames)
    Console.Write(s + );

Subconsultas em uma expressão de consulta

var queryGroupMax =
     student  students
     student  student.GradeLevel  studentGroup
     
    {
        Level = studentGroup.Key,
        HighestScore =
            ( student2  studentGroup
              student2.Scores.Average())
             .Max()
    };

Conceitos

Referência

Outros recursos