Compartilhar via

Filtrar linhas usando FetchXML

Para definir condições nas linhas de dados a serem retornadas, use o elemento de filtro dentro de uma entidade, entidade de link ou outro filter elemento.

Para definir as condições, adicione um ou mais elementos de condição ao filtro. O atributo que contém filtertype determina se todas (and) ou qualquer (or) das condições devem ser atendidas. O padrão é and. Ao aninhar elementos de filtro, você pode criar critérios de filtro complexos que combinam critérios avaliados usando and ou or.

Cada condition possui um atributo operator para avaliar o valor de uma coluna da linha. Você pode escolher entre muitos valores de operador de condição.

Por exemplo, a consulta a seguir retorna registros de conta em que address1_city é igual a "Redmond". Ele usa <filter type='and'> com o operador eq.

<fetch>
   <entity name='account'>
      <attribute name='name' />
      <filter type='and'>
         <condition attribute='address1_city'
            operator='eq'
            value='Redmond' />
      </filter>
   </entity>
</fetch>

Esta consulta retorna registros de conta que address1_city são iguais a "Redmond", "Seattle" ou "Bellevue". Ele usa o <filter type='or'> com três elementos de condição, cada um utilizando o operador eq.

<fetch>
   <entity name='account'>
      <attribute name='name' />
      <attribute name='address1_city' />
      <filter type='or'>
         <condition attribute='address1_city'
            operator='eq'
            value='Redmond' />
         <condition attribute='address1_city'
            operator='eq'
            value='Seattle' />
         <condition attribute='address1_city'
            operator='eq'
            value='Bellevue' />
      </filter>
   </entity>
</fetch>

Você também pode representar a consulta anterior usando o operador in com um único condition elemento. Essa condição contém vários elementos de valor para especificar valores para comparação com address1_city.

<fetch>
   <entity name='account'>
      <attribute name='name' />
      <attribute name='address1_city' />
      <filter type='and'>
         <condition attribute='address1_city'
            operator='in'>
            <value>Redmond</value>
            <value>Seattle</value>
            <value>Bellevue</value>
         </condition>
      </filter>
   </entity>
</fetch>

Parâmetros de operador

Os operadores não podem exigir parâmetros, um único parâmetro ou vários parâmetros. O operador determina como você define o valor a ser avaliado.

Sem parâmetros

Alguns operadores não exigem parâmetros. Por exemplo, use o operador eq-userid para avaliar qualquer identificador exclusivo e determinar se ele corresponde à ID do usuário de chamada.

<condition attribute='ownerid'
   operator='eq-userid' />

Parâmetro único

Quando um operador exigir um único parâmetro, use o value atributo para definir o valor a ser avaliado. Por exemplo, use o operador eq para avaliar o statecode valor da coluna de escolha de um registro definindo o value atributo.

<condition attribute='statecode'
   operator='eq'
   value='0' />

Vários parâmetros

Quando um operador exigir vários parâmetros, use o elemento valor para especificar os valores a serem avaliados. Por exemplo, use o operador entre para avaliar um número para determinar se ele está entre um conjunto de valores.

<condition attribute="numberofemployees"
   operator="between">
   <value>6</value>
   <value>20</value>
</condition>

Quando você aplica um filtro em uma entidade de link, o filtro é aplicado com a junção, a menos que você configure o filtro para ocorrer após a junção.

Quando o valor do atributo link-entitylink-type for outer, talvez você queira aplicar o filtro após a junção definindo o valor do atributo de condiçãoentityname. Se você estiver usando um link-entityalias, use o valor alias para definir o atributo entityname. Caso contrário, defina o valor do atributo entityname para o valor de link-entityname do atributo.

Por exemplo, a consulta a seguir retorna contatos sem uma conta pai ou uma conta pai sem um fax.

<fetch>
  <entity name='contact'>
    <attribute name='fullname' />
    <filter>
      <condition entityname='a'
        attribute='fax'
        operator='null' />
    </filter>
    <link-entity name='account'
      from='accountid'
      to='parentcustomerid'
      link-type='outer'
      alias='a' />
  </entity>
</fetch>

Filtrar com base nos valores das colunas na mesma linha

Você pode criar filtros que comparam colunas em valores na mesma linha usando o valueof atributo. Por exemplo, se você quiser encontrar registros de contato em que o valor da firstname coluna corresponda ao valor da lastname coluna, use esta consulta:

<fetch>
   <entity name='contact' >
      <attribute name='firstname' />
      <filter>
         <condition attribute='firstname'
            operator='eq'
            valueof='lastname' />
      </filter>
   </entity>
</fetch>

Comparações entre colunas de tabela

Usando apenas FetchXML, você pode comparar valores de campo em tabelas relacionadas. O exemplo a seguir retorna linhas em que a coluna de contato fullname corresponde à coluna da conta name .

<fetch>
   <entity name='contact'>
      <attribute name='contactid' />
      <attribute name='fullname' />
      <filter type='and'>
         <condition attribute='fullname'
            operator='eq'
            valueof='acct.name' />
      </filter>
      <link-entity name='account'
         from='accountid'
         to='parentcustomerid'
         link-type='outer'
         alias='acct'>
         <attribute name='name' />
      </link-entity>
   </entity>
</fetch>

O elemento de entidade de link deve usar um alias atributo e o valor do valueof parâmetro deve referenciar esse alias e o nome da coluna na tabela relacionada.

Limitações em filtros de comparação de colunas

Esses tipos de filtros têm as seguintes limitações:

  • Condição só pode usar estes operadores:

    Operador Descrição
    eq Os valores são comparados quanto à igualdade.
    ne Os dois valores não são iguais.
    gt O valor é maior que o valor comparado.
    ge O valor é maior ou igual ao valor comparado.
    lt O valor é menor que o valor comparado.
    le O valor é menor ou igual ao valor comparado.

  • Você pode comparar apenas duas colunas de cada vez.

  • Não há suporte para operações de condição estendidas. Por exemplo: valueof='amount'+ 100.

  • As colunas devem ser do mesmo tipo. Por exemplo: você não pode comparar um valor de cadeia de caracteres com um valor numérico.

Para filtrar valores em registros relacionados sem retornar esses valores, use um elemento de entidade de link dentro do elemento de filtro com um dos seguintes link-type atributos:

Nome Descrição
any Use isso em um elemento de filtro. Restringe os resultados a linhas pai com todas as linhas correspondentes na entidade vinculada.
not any Use isso em um elemento de filtro. Restringe os resultados a linhas pai sem linhas correspondentes na entidade vinculada.
all Use isso em um elemento de filtro. Restringe os resultados a linhas pai onde existem linhas com valor de coluna correspondente from na entidade de vínculo, mas nenhuma dessas linhas correspondentes satisfaz os filtros adicionais definidos para essa entidade de vínculo. Você precisa inverter os filtros adicionais para encontrar linhas pai onde cada linha de entidade de link correspondente satisfaça alguns critérios adicionais.
not all Use isso em um elemento de filtro. Restringe os resultados a linhas pai com qualquer linha correspondente na entidade vinculada. Esse tipo de link é equivalente a any apesar do nome.

Quando você usa esses tipos de link dentro de um elemento de filtro, esses filtros são condições filho que seguem o comportamento definido pelo type atributo do pai.filter

Os filtros que usam esses tipos retornam a linha pai no máximo uma vez, mesmo que existam várias linhas correspondentes na entidade de link. Eles não retornam os valores das colunas das linhas da entidade vinculada.

Os exemplos a seguir demonstram a filtragem em valores de registros relacionados. Esses exemplos incluem as instruções SQL equivalentes para ajudar a explicar o comportamento.

Essa consulta usa um filter tipo or com um filho link-entity do tipo any para retornar registros em contato que:

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='or'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='any'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
         <condition attribute='statecode'
            operator='eq'
            value='1' />
      </filter>
   </entity>
</fetch>

Essa consulta usa o not any tipo de link para retornar registros da tabela de contatos que não são referenciados pela coluna de pesquisa PrimaryContactId de qualquer registro de conta que tenha sua coluna Name igual a Contoso. O registro de contato ainda pode ser referenciado por registros de conta com outros valores na coluna Name.

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='and'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='not any'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
      </filter>
   </entity>
</fetch>

Observação

O significado dos tipos de link all e not all é o oposto do que os nomes podem sugerir, e normalmente são usados com filtros invertidos.

  • Uma entidade de link do tipo not all é equivalente a any e retorna registros pai, que têm registros de entidade de link correspondentes aos filtros.
  • Uma entidade de link do tipo all retorna registros pai quando alguns registros de entidade de vínculo com um valor de coluna correspondente from existem, mas nenhuma dessas linhas de entidade de link satisfaz os filtros adicionais definidos dentro do elemento de entidade de link.

Essa consulta usa um link-entity tipo not all para retornar registros da tabela de contatos referenciados pela coluna de pesquisa PrimaryContactId de pelo menos um registro de conta que tenha sua coluna Name igual a Contoso:

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='and'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='not all'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
      </filter>
   </entity>
</fetch>

Essa consulta usa um link-entity do tipo all para retornar registros da tabela contato que são referenciados pela coluna de busca PrimaryContactId de algumascontas, mas nenhuma dessas contas tem sua coluna Name igual a Contoso:

<fetch>
   <entity name='contact'>
      <attribute name='fullname' />
      <filter type='and'>
         <link-entity name='account'
            from='primarycontactid'
            to='contactid'
            link-type='all'>
            <filter type='and'>
               <condition attribute='name'
                  operator='eq'
                  value='Contoso' />
            </filter>
         </link-entity>
      </filter>
   </entity>
</fetch>

Limites de condição

Você pode incluir até 500 elementos de condição total e entidade de link em uma consulta FetchXML. Caso contrário, você verá esta mensagem de erro:

Nome: TooManyConditionsInQuery
Código: 0x8004430C
Número: -2147204340
Mensagem: Number of conditions in query exceeded maximum limit.

Você precisa reduzir o número de condições para executar a consulta. Você pode reduzir o número de condições usando o operador in que pode usar com números, identificadores exclusivos e cadeias de caracteres até 850 caracteres.

Próximas Etapas 

Saiba como paginar resultados.

Resultados da página

  • Last updated on