Este é o site histórico da documentação 4D. As documentações estão sendo movidas progressivamente para developer.4d.com |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
4D v19.8
dataClass.query( )
|
dataClass.query ( stringPesq {; valor}{; valor2 ; ... ; valorN}{; confPesq}) -> Resultado | ||||||||
Parâmetro | Tipo | Descrição | ||||||
stringPesq | Texto, Objeto |
![]() |
Critério de pesquisa | |||||
valor | Mixed |
![]() |
VAlores a comparar quando usar placeholders | |||||
confPesq | Objeto |
![]() |
Opções de pesquisa: parâmetros, atributos, argumentos, allowFormulas,context, rotaPesq, planoPesq | |||||
Resultado | EntitySelection |
![]() |
Nova seleção de entidade feita de entidades do dataClass que atendem aos critérios de pesquisa | |||||
O método dataClass.query( ) busca entidades que cumpram os critérios de pesquisa especificados en stringPesq ou formula 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.
O parâmetro stringPesq utiliza a sintaxe abaixo:
attributePath|formula comparator value {logicalOperator attributePath|formula comparator value} {order by attributePath {desc | asc}}
onde:
Note: Não é possível pesquisar em atributos cujo nome contenha caracteres especiais tais como".", "[ ]", o "=", ">", "#"..., já que avaliarão incorretamente na pesquisa de string. Se necessitar consultar ditos atributos, deve considerar o uso de marcadores de posição (placeholders), que permitem uma range estendida de caracteres nas rotas de atributos (ver parâmetros de valor (e placeholders) abaixo).
"eval(length(This.lastname) >=30)"
(*) se a fórmula não for o único critério de pesquisa, o otimizador de motor de pesquisa poderia processar por outros critérios (por exemplo atributos indexados) e assim, a fórmula poderia ser avaliada para apenas um subconjunto de entidades.
Fórmulas em pesquisas podem receber parâmetros através de $1. Este ponto é detalhado no parágrafo abaixo formula parameter.
Notas:
- Também pode passar diretamente um parâmetro de objeto formula ao invés do parâmetro queryString (recomendado quando as fórmulas são mais complexas). Veja o parágrafo abaixo formula parameter.
- Para razões de segurança, chamadas de fórmula dentro dos métodos membro query() podem ser desativados. Veja a descrição do parâmetro queryString.
Comparação | Símbolo(s) | Comentário |
Equal to | =, == | Obtém dados que coincidem, considera 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, compatível com coringa (@) |
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 |
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'"
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')"
Como alternativa à inserção de fórmulas dentro do parâmetro stringPesq (ver acima), pode passar diretamente um objeto formula como um criterio de pesquisa booleano. Se recomenda utilizar um objeto fórmula para consultas, já que se beneficia da tokenização e o código fica mais fácil de buscar/ler.
A fórmula deve ser criada com o comando Formula ou Formula from string. Neste caso:
Nota: por razões de segurança, as chamadas de fórmula dentro dos métodos query() podem ser recusadas. Ver a descrição do parâmetro stringPesq.
Passando parâmetros a fórmulas
Toda fórmula chamada pelo método membro query() pode receber parâmetros:
Este pequeno código mostra os principios de como passar os parâmetros aos métodos:
$settings:=New object("args";New object("exclude";"-")) //objeto args para passar parâmetros
$es:=ds.Students.query("eval(checkName($1.exclude))";$settings) //args é recebido em $1
São apresentados exemplos adicionais no exemplo 3.
4D Server: em cliente/servidor, as fórmulas são executadas no servidor. Neste contexto, apenas o objeto querySettings.args é enviado às fórmulas.
4D lhe permite utilizar marcadores de posição (placeholders) para os argumentos rotaAtributo formula e valor dentro do parâmetro params. Um marcador de posição é um parâmetro que se inserta nas strings de pesquisa e que se substitui por outro valor quando for avaliada a string de pesquisa. O valor dos marcadores de posição é avaliada uma vez no início da consulta; Não se avalia para cada elemento.
Podem ser utilizados dois tipos de marcadores de posição: marcadores de posição indexados e marcadores de posição com nome:
- | Marcadores de posição indexados | Marcadores de posição com nome |
Definição | os parâmetros se inserem como :paramIndex (por exemplo :1, :2...) em stringPesq e seus valores correspondentes se proporcionam mediante a sequência dos parâmetros valor. Pode utilizar até 128 parâmetros valor | Os parâmetros se inserem como: paramName (por exemplo: myparam) e seus valores se proporcionam nos objetos parâmetros ou atributos no parâmetro params. |
Exemplo | $r:=class.query(":1=:2";"city";"Chicago") | $o.attributes:=New object("att";"city") |
Usar placeholders (marcadores de posição) em pesquisas é recomendado por duas razões:
$vquery:="status = 'public' & name = "+myname //usuário insere seu nome
&NBSP;&NBSP;&NBSP;$result:=$col.query($vquery)
$result:=$col.query("status='public' & name=:1";$myvar)
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
$vSingles:=ds.Person.query("spouse = null") //sintaxe correta
Quando pesquisar em coleções dentro de atributos de objeto usando múltiplos argumentos de pesquisa unidos pelo operador AND, pode querer ter certeza que apenas entidades contendo elementos que correspondem a todos os elementos são retornados, e não entidades cujos argumentos podem ser encontrados em diferentes elementos. Para fazer isso, precisa linkar argumentos de pesquisa a elementos de coleção, para que apenas elementos únicos contendo argumentos linkados sejam encontrados.
Por exemplo, com as duas entidades abaixo:
Entidade 1:
ds.People.name: "martin"
ds.People.places:
{ "locations" : [ {
"kind":"home",
"city":"paris"
} ] }
Entidade 2:
ds.People.name: "smith"
ds.People.places:
{ "locations" : [ {
"kind":"home",
"city":"lyon"
} , {
"kind":"office",
"city":"paris"
} ] }
Se quiser encontrar pessoas com uma localização do tipo "home" (casa) na cidade "paris" pode escrever:
ds.People.query("places.locations[].kind= :1 and places.locations[].city= :2";"home";"paris")
... a pesquisa retorna "martin" and "smith" porque "smith" tem um elemento "locations" cujo "kind" (tipo) é "home" e um elemento "locations" cuja "city" é "paris", mesmo sendo elementos diferentes.
Se quiser obter apenas entidades onde os argumentos correspondentes estejam no mesmo elemento de coleção, precisa linkar argumentos. Para linkar argumentos de pesquisa:
Com as entidades acima, se escrever:
ds.People.query("places.locations[a].kind= :1 and places.locations[a].city= :2";"home";"paris")
... a pesquisa vai retornar apeans "martin" porque tem um elemento "locations" cujo "kind"é "home" e cuja "city" é "paris". A pesquisa não vai retornar "smith" porque os valores "home" e "paris" não estão no mesmo elemento de coleção.
Note: Este parâmetro é compatível apenas com os métodos entitySelection.query( ) e dataClass.query( ).
No parâmetro params, pode passar um objeto contendo opções adicionais. As propriedades abaixo são compatíveis:
Propriedade | Tipo | Descrição | ||||||
parameters | Objeto | Marcadores de posição nomeados para os valores utilizados em cadenaBusq. Os valores se expresam como pares propriedade / valor, onde propriedade é o nome de marcador de posição insertado para um valor em cadenaBusq (": placeholder") e o valor é o valor a comparar. Pode combinar marcadores de posição indexados (valores diretamente passados em parâmetros valor) e valores de marcador de posição com nome na mesma consulta. | ||||||
attributes | Objeto | Marcadores de posição nomeados para as rotas de atributo utilizadas em cadenaBusq. Os atributos se expressam como pares de propriedade / valor, onde propriedade é o nome de marcador de posição insertado para uma rota de atributo em cadenaBusq (":placeholder"), e valor pode ser uma string ou uma coleção de strings. Cada valor é uma rota que pode designar um escalar ou um atributo relacionado da classe de dados ou uma propriedade em um campo de objeto da classe de dados
| ||||||
args | Object | Parâmetros para pasasr às fórmulas, se houver. Os args objeto será recebido em $1 dentro de fórmulas e assim seus valores estarão disponíveis através de $1.property (ver exemplo 3). | ||||||
allowFormulas | Boolean | True para permitir a chamada de fórmula na pesquisa (padrão). Passe false para desativar a execução da fórmula. Se estabelecer como falsa e query() é dado como uma fórmula, um erro é enviado (1278 - Formula não permitida em member method | ||||||
context | Texto | Etiqueta para o contexto de otimização automatica aplicado à seleção de entidades. Este contexto será utilizado pelo código que maneja a seleção de entidades para que possa beneficiar-se da otimização. Esta funcionalidade está criada para o processamento cliente/servidor; Para saber mais, consulte Client/server optimization. | ||||||
queryPlan | Booleano | Na seleção de entidades resultante, devolve ou não devolve a descrição detalhada da pesquisa justo antes de que se execute, ou seja, a consulta programada. A propriedade devolvida é um objeto que inclui cada consulta planificada e subconsulta (no caso de uma consulta complexa). Esta opção é útil durante a fase de desenvolvimento de uma aplicação. Em geral, se utiliza junto com queryPath. Como padrão se omite: false. | ||||||
Nota: esta propriedade apenas é compatível com os métodos entitySelection.query( ) e dataClass.query( ). | ||||||||
queryPath | Booleano | Na seleção de entidades resultante, devolve ou não devolve a descrição detalhada da consulta, já que realmente se realiza. A propriedade devolvida é um objeto que contém a rota real utilizada para a consulta (geralmente idêntica à de queryPlan, mas pode diferir se o motor conseguir otimizar a consulta), assim como o tempo de processamento e o número de registros encontrados. Esta opção é útil durante a fase de desenvolvimento de uma aplicação. Como padrão é omitida: false. Nota: esta propriedade só é compatível com os métodos entitySelection.query( ) e dataClass.query( ). |
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}]}]}]}]}
Esta seção fornece exemplos de pesquisas
Pesquisa em string:
$entitySelection:=ds.Customer.query("firstName = 'S@'")
Pesquisa com uma declaração NOT:
$entitySelection:=ds.Employee.query("not(firstName=Kim)")
Pesquisa com datas:
$entitySelection:=ds.Employee.query("birthDate > :1";"1970-01-01")
$entitySelection:=ds.Employee.query("birthDate <= :1";Current date-10950)
Pesquisa com placeholders (caractere de reposição) indexados para valores:
$entitySelection:=ds.Customer.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@")
Pesquisa com placeholders indexados para valores em uma dataClass relacionada:
$entitySelection:=ds.Employee.query("lastName = :1 and manager.lastName = :2";"M@";"S@")
Pesquisa com placeholder indexado incluindo uma ordem descendente por declaração:
$entitySelection:=ds.Student.query("nationality = :1 order by campus.name desc, lastname";"French")
Pesquisa com placeholders nomeados para valores:
C_OBJECT($querySettings;$managedCustomers)
$querySettings:=New object
$querySettings.parameters:=New object("userId";1234;"extraInfo";New object("name";"Smith"))
$managedCustomers:=ds.Customer.query("salesperson.userId = :userId and name = :extraInfo.name";$querySettings)
Pesquisa que usa placeholders nomeados e indexados para valores:
C_OBJECT($querySettings;$managedCustomers)
$querySettings:=New object
$querySettings.parameters:=New object("userId";1234)
$managedCustomers:=ds.Customer.query("salesperson.userId = :userId and name=:1";"Smith";$querySettings)
Pesquisa com objetos queryPlan e queryPath:
$entitySelection:=ds.Employee.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@";New object("queryPlan";True;"queryPath";True))
//pode conseguir estas propriedades na seleção de entidades resultante
C_OBJECT($queryPlan;$queryPath)
$queryPlan:=$entitySelection.queryPlan
$queryPath:=$entitySelection.queryPath
Pesquisa com uma rota de atributo de tipo Collection:
$entitySelection:=ds.Employee.query("additionalInfo.hobbies[].name = :1";"horsebackriding")
Pesquisa com uma rota de atributo de tipo Collection e atributos linkados:
$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and extraInfo.hobbies[a].level=:2";"horsebackriding";2)
Pesquisa com uma rota de atributo de tipo Collection e múltiplos atributos linkados
$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and extraInfo.hobbies[a].level = :2 and extraInfo.hobbies[b].name = :3 and extraInfo.hobbies[b].level = :4";"horsebackriding";2;"Tennis";5)
Pesquisa com uma rota de atributo de tipo Object:
$entitySelection:=ds.Employee.query("extra.eyeColor = :1";"blue")
Pesquisa com uma declaração IN:
$entitySelection:=ds.Employee.query("firstName in :1";New collection("Kim";"Dixie"))
Pesquisa com uma declaração NOT (IN):
$entitySelection:=ds.Employee.query("not (firstName in :1)";New collection("John";"Jane"))
Pesquisa com placeholders indexados para atributos:
C_OBJECT($es)
$es:=ds.Employee.query(":1 = 1234 and :2 = 'Smith'";"salesperson.userId";"name")
//salesperson (pessoal de vendas) é uma entidade relacionada
Pesquisa com placeholders indexados para atributos e placeholders nomeados para valores:
C_OBJECT($es;$querySettings)
$querySettings:=New object
$querySettings.parameters:=New object("customerName";"Smith")
$es:=ds.Customer.query(":1 = 1234 and :2 = :customerName";"salesperson.userId";"name";$querySettings)
//salesperson é uma entidade relacionada
Pesquisa com placeholders indexados para atributos e valores
C_OBJECT($es)
$es:=ds.Clients.query(":1 = 1234 and :2 = :3";"salesperson.userId";"name";"Smith")
//salesperson is a related entity
Esta seção ilustra as pesquisas com os marcadores de posição com nome para os atributos.
Dada uma dataclass Employee com 2 entidades:
Pesquisa com os marcadores de posição com nome para os atributos:
C_OBJECT($querySettings;$es)
$querySettings:=New object
$querySettings.attributes:=New object("attName";"name";"attWord";New collection("softwares";"Word 10.2"))
$es:=ds.Employee.query(":attName = 'Marie' and :attWord = 'Installed'";$querySettings)
//$es.length=1 (Employee Marie)
Pesquisa com os marcadores de posição com nome para os atributos e os valores:
C_OBJECT($es;$queySettings)
C_TEXT($name)
$querySettings:=New object
//Named placeholders for values
//The user is asked for a name
$name:=Request("Please enter the name to search:")
If(OK=1)
$querySettings.parameters:=New object("givenName";$name)
//Named placeholders for attribute paths
$querySettings.attributes:=New object("attName";"name")
$es:=ds.Employee.query(":attName= :givenName";$querySettings)
End if
Estes exemplos ilustram as várias maneiras para usar fórmulas com ou sem parâmetros em suas pesquisas.
A fórmula é dada como texto com eval() no parâmetro queryString:
C_OBJECT($es)
$es:=ds.Students.query("eval(length(This.lastname) >=30) and nationality='French'")
A fórmula é dada como um objeto Formula através de um placeholder:
C_OBJECT($es;$formula)
$formula:=Formula(Length(This.lastname)>=30)
$es:=ds.Students.query(":1 and nationality='French'";$formula)
Só um objeto Fórmula é dado como critério:
C_OBJECT($es;$formula)
$formula:=Formula(Length(This.lastname)>=30)
$es:=ds.Students.query($formula)
Várias fórmulas podem ser aplicadas:
C_OBJECT($formula1;$1;$formula2;$0)
$formula1:=$1
$formula2:=Formula(Length(This.firstname)>=30)
$0:=ds.Students.query(":1 and :2 and nationality='French'";$formula1;$formula2)
Uma fórmula texto em queryString recebe um parâmetro:
C_OBJECT($es;$settings)
$settings:=New object()
$settings.args:=New object("filter";"-")
$es:=ds.Students.query("eval(checkName($1.filter)) and nationality=:1";"French";$settings)
//método checkName:
C_TEXT($1;$exclude)
$exclude:=$1
$0:=(Position($exclude;This.lastname)=0)
Usar o mesmo nome checkName, um objeto Formula como placeholder recebe um parâmetro:
C_OBJECT($es;$settings;$formula)
$formula:=Formula(checkName($1.filter))
$settings:=New object()
$settings.args:=New object("filter";"-")
$es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)
$settings.args.filter:="*" // change the parameters without updating the $formula object
$es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)
Se quiser desativar fórmulas, por exemplo quando o usuário digitar sua pesquisa:
C_OBJECT($es;$settings)
C_TEXT($queryString)
$queryString:=Request("Enter your query:")
if(OK=1)
$settings:=New object("allowFormulas";False)
$es:=ds.Students.query($queryString;$settings) //Um erro é levantado se $queryString conter uma formula
End if
4D Blog - Add values to your generic orda queries
4D Blog - Placeholders for attribute paths in ORDA queries
collection.query( )
dataClass.all( )
dataClass.newSelection( )
DESCRIBE QUERY EXECUTION
entitySelection.query( )
entitySelection.queryPath
entitySelection.queryPlan
GET QUERY DESTINATION
QUERY
SET QUERY DESTINATION
Produto: 4D
Tema: ORDA - DataClass
Criado por: 4D v17
Modificado: 4D v17 R5
Modificado: 4D v17 R6
Manual de linguagem 4D ( 4D v19)
Manual de linguagem 4D ( 4D v19.1)
Manual de linguagem 4D ( 4D v19.4)
Manual de linguagem 4D ( 4D v19.5)
Manual de linguagem 4D ( 4D v19.6)
Manual de linguagem 4D ( 4D v19.7)
Manual de linguagem 4D ( 4D v19.8)