dataClass.query( )

4D v17.4

dataClass.query( )

Descrição

O método dataClass.query( ) busca entidades que cumpram os critérios de pesquisa especificados en stringPesq e (opcionalmente) valor, para todas as entidades em dataClass ou entitySelection, e devolve um novo objeto de tipo EntitySelection que contém todas as entidades de dataClass que forem encontradas. Se aplica um carregamento lento (lazy loading).

Se não forem encontradas entidades coincidentes, se devolve uma EntitySelection vazia.

Parâmetro queryString paramete

O parâmetro stringPesq utiliza a sintaxe abaixo:

attributePath comparator value {logicalOperator attributePath comparator value}

onde:

attributePath: nome do atributo de classe de dados no qual deseja executar a pesquisa, por exemplo, "country". Este parâmetro pode ser qualquer rota de atributo válida, como "country.name".
No caso de uma rota de atributo cujo tipo for Collection, a notação [] é usada para manejar todas as ocorrências.

Note: Não é possível pesquisar em atributos cujo nome contenha caracteres especiais tais como "." ou "[ ]" já que avaliarão incorretamente na pesquisa de string. Para saber mais, veja o parágrafo identificador notação objeto. Além disso, nomes de atributo não podem conter símbolos tais como "=", ">", "#"..., que podem ser interpretados como comparadores (ver abaixo).

comparator: símbolo que compara rotaAtributo e valor. Os símbolos abaixo são compatíveis:

Comparação	Símbolo(s)	Comentário
Equal to	=, ==	Obtém dados coincidentes, admite o caractere coringa (@), não diferencia entre maiúsculas e minúsculas nem diacrítico.
	===, is	Obtém dados que coincidem, considera o caractere coringa (@) como um caractere padrão, não distingue entre maiúsculas e minúsculas nem é diacrítico
Not equal to	#, !=	compatível com coringa (@)
	!==, IS NOT	Considera o coringa (@) como um caractere comum,
	#, !=, is not
Less than	<
Greater than	>
Less than or equal to	<=
Greater than or equal to	>=
Included in	IN	Obtém dados iguais para ao menos um dos valores em uma coleção ou em um conjunto de valores
Not condition applied on a statement	NOT	Os parêntesis são obrigatórios quando se usa Not antes de uma instrução que contenha vários operadores
Contains keyword	%	As palavras chave podem ser usadas em atributos de string ou tipo de imagem

value: o valor a comparar com o valor atual da propriedade de cada objeto na coleção ou seleção de entidade. Pode ser qualquer expressão do mesmo tipo de dados que a propriedade ou um separador de posição: paramIndex (ver abaixo).
Os valores constantes se dão entre aspas simples. As palavras chaves a seguir estão proibidas para as constantes: true, false. Pode comparar o valor Null em uma pesquisa utilizando a palavra chave "null". Esta pesquisa encontrará propriedades null e undefined.
Para buscar uma string dentro de uma string (uma pesquisa "contém"), utilize o símbolo coringa (@) em valor para isolar a string que vai ser pesquisada como é mostrada neste exemplo: "@Smith@".
Para valores numéricos, os separadores decimais são o ponto. As datas devem ser dadas com o formato "AAAA-MM-DD".
No caso de uma pesquisa com um comparador IN, valor deve ser uma coleção, ou valores que coincidam com o tipo da rota do atributo entre [] separados por vírgulas (para strings, "os caracteres devem escapar com "\").

logicalOperator: utilizado para unir múltiplas condições na pesquisa (opcional). Pode usar um dos operadores lógicos abaixo (pode passar o nome ou o símbolo):
Conjunção Símbolo(s)
AND &, &&, and
OR |, ||, ou

Utilizando aspas
quando utilizar aspas dentro de pesquisas, deve usar aspas simples ' ' dentro da pesquisa e aspas duplas " " para abarcar toda a pesquisa, do contrário, se devolve um erro. Por exemplo:

"employee.name = 'smith' AND employee.firstname = 'john'"

Nota: as aspas simples (') não são compatíveis com os valores pesquisados, já que romperiam a string de consulta. Por exemplo, "comp.name = 'John's pizza' " gerará um erro. Se necesitar buscar valores com aspas simples, pode considerar o uso de marcadores de posição (ver abaixo).

Utilizando parêntesis
Pode utilizar parêntesis em pesquisas para dar prioridade ao cálculo. Por exemplo, pode organizar uma pesquisa da maneira abaixo:

"(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"

value parameter (and placeholders)

O parâmetro valor devem ser usados quando a pesquisa for construida com placeholders (marcadores de posição) usados quando a pesquisa é construida com placeholders. Placeholders são tags (etiquetas) que podem ser inseridas em strings de pesquisa e que podem ser substituídas por outro valor quando a string de pesquisa for avaliada. Pode usar até 128 parâmetros de valoes

Nota: Valores para placeholders também podem ser passados como uma coleção na propriedade parâmetros do parâmetro opcional querySettings (apenas para entitySelection e pesquisas dataClass). Para saber mais veja o parágrafo parâmetros confPesqSetting.

Em queryString, insert :paramIndex para cada placeholder (o que significa "use o parâmetro paramIndex da pesquisa como o valor a comparar=") e então passe os valores exigidos como parâmetors valores. Por exemplo, para uma pesquisa para empregados morando em Chicago e ganhando menos de 10 000, pode escrever:

"employee.city = :1 & employee.salary < :2"; "Chicago";10000

O valor é avaliado uma vez ao início da pesquisa: não é avaliada para cada elemento.

Usar placeholders (marcadores de posição) em pesquisas é recomendado por duas razões:

Previne inserção de código malicioso: se usar diretamente variáveis preenchidas-por-usuário dentro da string pesquisa, um usuário pode modificar as condições de pesquisa entrando argumentos adicionais de pesquisa. Por exemplo, imagine uma string de pesquisa como:
$vquery:="status = 'public' & name = "+myname //usuário insere seu nome &NBSP;&NBSP;&NBSP;$result:=$col.query($vquery)

Essa pesquisa parece segura já que dados não públicos são filtrados. Entretanto, se o usuário entrar na área $myvar algo como OR status='private', a string de pesquisa seria modificada no passo de interpretação e poderia retornar dados privados.
Quando usar placeholders, sobrepujar condições de segurança não é possível:
$result:=$col.query("status='public' & name=:1";$myvar)

Nesse caso se o usuário entrar OR status='private' na área $myvar, não vai ser interprertada na string de pesquisa, mas apenas passada como um valor. Procurar por uma pessoa nomeada"OR status='private'" vai apenas falhar.
Previne preocupação com problemas de formatação. Além disso, permite o uso de variáveis ou expressões em argumentos de pesquisa
Exemplos:
$result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@") &NBSP;&NBSP;&NBSP;$result2:=$col.query("company.name = :1";"John's Pizzas")

Procurar por valores null
Quando procurar por valores null, não é possível usar a sintaxe placeholder porque o motor de pesquisa considera null como um valor de comparação inesperado. Por exemplo, se executar a pesquisa abaixo:

$vSingles:=ds.Person.query("spouse = :1";Null) // NAO funciona

Não vai obter o valor esperado porque o valor null será avaliado por 4D como um erro resultante da avaliação do parâmetro (por exemplo, um atributo vindo de outra pesquisa). Para esses tipos de pesquisa, deve usar a sintaxe de pesquisa direta:

$vSingles:=ds.Person.query("spouse = null") //sintaxe correta

parâmetros confPesqSetting

Note: Este parâmetro é compatível apenas com os métodos entitySelection.query( ) e dataClass.query( ).

No parâmetro confPesq, pode passar um objeto contendo opções adicionais. As propriedades abaixo são compatíveis:

Propriedade	Tipo	Descrição
parameters	Collection	Valores a comparar quando usar placeholders em stringPesq (modo alternativo de passar valores aos placeholders). Se alguns valores também forem passados diretamente no parâmetro valo, estes valores são anexados na sequência do placeholder.
planPesq	Boolean	Na coleção de entidade resultante, retorna ou não retorna a descrição detalhada da pesquisa imediatamente antes de ser executada, ou seja, a pesquisa planejada. A propriedade retornada é um objeto que inclui cada pesquisa planejada e subpesquisa no caso de uma pesquisa complexa. Esta opção é útil durante a fase de desenvolvimento da aplicação. É geralmente usada em conjunção com rotaPesq. Padrão se omitido: false
rotaPesq	Boolean	Na coleção de entidade resultante, retorna ou não retorna a descrição detalhada da pesquisa como é realizada atualmente. A propriedade retornada é um objeto que contém a rota verdadeira usada para a pesquisa (geralmente idêntica a aquela de planoPesquisa mas pode ser diferente se o motor conseguir otimizar a pesquisa), assim como o tempo de processamento e o número de registros encontrados. Esta opção é útil durante a fase de desenvolvimento da aplicação. Padrão se omitido: false

Sobre planoPesq e rotaPesq
A informação gravada em planoPesq/rotaPesq inclui o tipo de pesquisa (indexado e sequencial) e cada subpesquisa necessária junto com os operadores de conjunção. Rotas de pesquisa contém o número de entidades encontradas e o tempo necessário para executar cada critério de pesquisa. Pode ser útil analisar esta informação enquanto desenvolve sua aplicação. Geralmente a descrição do plano de pesquisa e sua rota são idênticos mas podem ser diferentes porque 4D pode implementar otimizações dinâmicas quando uma pesquisa é executada de forma a melhorar a performance. Por exemplo, o motor 4D pode converter dinamicamente uma pesquisa indexada em uma sequencial se estimar que será mais rápida. Esse caso particular pode ocorrer quando o número de entidades sendo pesquisadas é baixo..

Por exemplo, se executar a pesquisa abaixo:

 $sel:=ds.Employee.query("salary < :1 and employer.name = :2 or employer.revenues > :3";50000;"Lima West Kilo";10000000;New object("queryPath";True;"queryPlan";True))

queryPlan:

{Or:[{And:[{item:[index : Employee.salary ] < 50000},{item:Join on Table : Company  :  Employee.employerID = Company.ID,subquery:[{item:[index : Company.name ] = Lima West Kilo}]}]},{item:Join on Table : Company  :  Employee.employerID = Company.ID,subquery:[{item:[index : Company.revenues ] > 10000000}]}]}

queryPath:

{steps:[{description:OR,time:63,recordsfounds:1388132,steps:[{description:AND,time:32,recordsfounds:131,steps:[{description:[index : Employee.salary ] < 50000,time:16,recordsfounds:728260},{description:Join on Table : Company  :  Employee.employerID = Company.ID,time:0,recordsfounds:131,steps:[{steps:[{description:[index : Company.name ] = Lima West Kilo,time:0,recordsfounds:1}]}]}]},{description:Join on Table : Company  :  Employee.employerID = Company.ID,time:31,recordsfounds:1388132,steps:[{steps:[{description:[index : Company.revenues ] > 10000000,time:0,recordsfounds:933}]}]}]}]}

Exemplos

Aqui há vários exemplos de consultas válidas.

Consulta normal com marcadores de posição:

 $entitySelection:=dataClass.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@")

Consulta normal sem marcadores de posição:

$entitySelection :=dataClass.query("firstName = 'S@'")

Consulta com uma dataClass relacionada:

$entitySelection:=dataClass.query("lastName = :1 and manager.lastName = :2";"M@";"S@")

Consulta com objetos queryPlan e queryPath:

 $entitySelection:=dataClass.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@";New object("queryPlan";True;"queryPath";True))

 

  //Pode obter estas propriedades na seleção de entidade resultante

 C_OBJECT($queryPlan;$queryPath)

 $queryPlan:=$entitySelection.queryPlan

 $queryPath:=$entitySelection.queryPath

Consulta com marcadores de posição e valores dados como uma coleção:

 $params:=New object

 $params.parameters:=New collection("D@";"R@";"S@";"K@")

 $entitySelection:=dataClass.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";$params)

Consulta com uma declaração NOT:

$entitySelection:=dataClass.query("not(firstName=Kim)")

Consulta com uma rota de atributo de tipo Collection:

$entitySelection:=dataClass.query("additionalInfo.hobbies[].name = horseriding")

Consulta com uma rota de atributo de tipo Object:

$entitySelection:=ds.Employee.query("extra.eyeColor = :1";"blue")

Consulta com uma declaração IN:

$entitySelection:=dataClass.query("firstName in :1";New collection("Kim";"Dixie"))

Consulta com uma instrução NOT (IN):

$entitySelection:=ds.Employee.query("not (firstName in :1)";New collection("John";"Jane"))

Consulta com uma data:

$entitySelection:=dataClass.query("birthDate > :1";"1970-01-01")

Ver também

collection.query( )
dataClass.all( )
dataClass.newSelection( )
entitySelection.query( )
entitySelection.queryPath
entitySelection.queryPlan