DataClass

Uma DataClass oferece uma interface de objeto a uma tabela do banco de dados. Todas as classes de dados de uma aplicação 4D estão disponíveis como uma propriedade de ds datastore.

Resumo

.attributeName : DataClassAttribute    objectos que estão disponíveis directamente como propriedades
.all ( { settings : Object } ) : 4D. EntitySelection    consulta a datastore para encontrar todas as entidades relacionadas com a dataclass e devolve-as como uma selecção de entidade
.fromCollection( objectCol : Collection { ; settings : Object } ) : 4D. EntitySelection    actualiza ou cria entidades no dataclass de acordo com a colecção de objectos objectCol, e devolve a selecção da entidade correspondente
.get( primaryKey : Integer { ; settings : Object } ) : 4D. Entity .get( primaryKey : Text { ; settings : Object } ) : 4D.    consulta a folha de dados para recuperar a entidade que corresponde ao parâmetro primaryKey
.getInfo() : Objeto    cria uma nova selecção de entidade, em branco e não partilhável, relacionada com o dataclass, em memória
.getInfo() : Objeto     devolve um objecto que fornece informação sobre o dataclass
.new() : 4D. Entity     cria em memória e devolve uma nova entidade em branco relacionada com a Dataclass
.newSelection( { keepOrder : Integer } ) : 4D. EntitySelection     cria uma nova selecção de entidade, em branco e não partilhável, relacionada com o dataclass, em memória
.query( queryString : Text { ; ...value : any } { ; querySettings : Object } ) : 4D. EntitySelection .query( formula : Object { ; querySettings : Object } ) : 4D. EntitySelection     pesquisa por entidades que satisfaçam os critérios de pesquisa especificados em queryString ou fórmula e (opcionalmente) valor(s)

.attributeName

Histórico

Versão	Mudanças
v17	Adicionado

.attributeName : DataClassAttribute

Descrição

Os atributos dos dataclasses são objectos que estão disponíveis directamente como propriedades destas classes.

Os objetos retornados são do tipo class DataClassAttribute. Esses objetos têm propriedades que podem ser lidas para obter informação sobre seus atributos dataclass.

Os objetos do atributo Dataclass podem ser modificados, mas a estrutura subjacente do banco de dados não será alterada.

Exemplo 1

$salary:=ds. Employee.salary //returns the salary attribute in the Employee dataclass
$compCity:=ds. Company["city"] //returns the city attribute in the Company dataclass

Exemplo 2

Considerando a seguinte estrutura do banco de dados:

var $firstnameAtt;$employerAtt;$employeesAtt : Object

 $firstnameAtt:=ds. Employee.firstname
  //{name:firstname,kind:storage,fieldType:0,type:string,fieldNumber:2,indexed:true,
  //keyWordIndexed:false,autoFilled:false,mandatory:false,unique:false}

 $employerAtt:=ds. Employee.employer
  //{name:employer,kind:relatedEntity,relatedDataClass:Company,
  //fieldType:38,type:Company,inverseName:employees}
  //38=Is object

 $employeesAtt:=ds. Company.employees
  //{name:employees,kind:relatedEntities,relatedDataClass:Employee,
  //fieldType:42,type:EmployeeSelection,inverseName:employer}
  //42=Is collection

Exemplo 3

Considerando as propriedades de tabela abaixo:

 var $sequenceNumberAtt : Object
 $sequenceNumberAtt=ds. Employee.sequenceNumber
  //{name:sequenceNumber,kind:storage,fieldType:0,type:string,fieldNumber:13,
  //indexed:true,keyWordIndexed:false,autoFilled:true,mandatory:false,unique:true}

.all()

Histórico

Versão	Mudanças
v17 R5	Compatibilidade do parâmetro settings
v17	Adicionado

.all ( { settings : Object } ) : 4D. EntitySelection

Parâmetro	Tipo		Descrição
settings	Objeto	->	Opção de construção: context
Resultados	4D. EntitySelection	<-	Referencias sobre todas as entidades relacionadas com a classe de dados

|

Descrição

The .all( ) function consulta a datastore para encontrar todas as entidades relacionadas com a dataclass e devolve-as como uma selecção de entidade.

As entidades são devolvidas na ordem padrão, que é inicialmente a ordem na qual foram criadas. Note no entanto que, se as entidades foram apagas e outras adicionadas, a ordem padrão não reflete mais sua ordem de criação.

Se nenhuma entidade correspondente for encontrada, uma seleção de entidade vazia é retornada.

Se aplica carregamento diferido/lazy loading.

settings

No parâmetro querySettings é possível passar um objeto que conteha opções adicionais. As propriedades abaixo são compatíveis:

Propriedade	Tipo	Descrição
context	Text	Etiqueta para o contexto de otimização aplicado a seleção de entidades. Este contexto será utilizado pelo código que maneja a seleção de entidades para que possa se beneficiar da otimização. Essa funcionalidade foi criada para processamento cliente/servidor de ORDA .

Exemplo

 var $allEmp : cs. EmployeeSelection
 $allEmp:=ds. Employee.all()

.fromCollection()

Histórico

Versão	Mudanças
v17 R5	Compatibilidade do parâmetro settings
v17	Adicionado

.fromCollection( objectCol : Collection { ; settings : Object } ) : 4D. EntitySelection

Parâmetro	Tipo		Descrição
objectCol	Collection	->	Coleção de objetos a mapear com entidades
settings	Objeto	->	Opção de construção: context
Resultados	4D. EntitySelection	<-	Seleção de entidades preenchidas da coleção

|

Descrição

A função .fromCollection() actualiza ou cria entidades no dataclass de acordo com a colecção de objectos objectCol, e devolve a selecção da entidade correspondente.

No parâmetro objectCol, passa uma coleção de objetos para criar novas entidades ou atualizar as existentes da classe de dados. Os nomes das propriedades devem ser os mesmos que os dos atributos da classe de dados. Se um nome de propriedade não existir na dataclass, é ignorado. Se um valor de atributo não for definido na coleção, seu valor será null.

O mapeamento entre os objetos da coleção e as entidades se realiza sobre os nomes de atributos e tipos coincidentes. Se uma propriedade de um objeto tiver o mesmo nome que um atributo de entidade mas seus tipos não corresponderem, o atributo da entidade não é preenchido.

Criar ou atualizar modos

Para cada objeto de objectCol:

• Se o objeto conter uma propriedade booleana "__NEW" estabelecida em false (ou não conter uma propriedade booleana "__NEW"), a entidade se atualiza ou se cria com os valores correspondentes das propriedades do objeto. Nenhuma comprovação é realizada com respeito à chave primária:
  • Se a chave primária for dada e existir, a entidade é atualizada. Nesse caso, a chave primária pode ser dada como etá ou com uma propriedade "__KEY" (preenchida com o valor da chave primária).
  • Se a chave primária for dada (como é) e não existir, a entidade é criada
  • Se a chave primária não for dada, a entidade é criada e o valor da chave primária é assignado com respeito às regras padrão de database.
• Se o objeto conter uma propriedade boolean "__NEW" estabelecida como true, a entidade é criada com os valores correspondente dos atributos de objeto. Uma comprovação é realizada com relação à chave primária:
  • Se a chave primária for dada (como está) e existir, um erro é enviado.
  • Se a chave primária for dada (como é) e não existir, a entidade é criada
  • Se a chave primária não for dada, a entidade é criada e o valor da chave primária é assignado com respeito às regras padrão de database.

    A propriedade "__KEY" que contém um valor só é tida em conta quando a propriedade "__NEW" está definida como false (ou é omitida) e existe uma entidade correspondente. Em todos os outros casos, o valor da propriedade "__KEY" é ignorado, o valor da chave primária deve ser passado "tal como está".

Entidades relacionadas

Os objetos de objectCol podem conter um ou mais objetos aninhados que apresentam uma ou mais entidades relacionadas, o que pode ser útil para criar ou atualizar links entre entidades.

Os objetos aninhados que apresentam entidades relacionadas devem conter uma propriedade "__KEY" (preenchido com o valor da chave primária da entidade relacionada) ou o atributo de chave primária da própria entidade relacionada. O uso de uma propriedade __KEY permite a independência do nome do atributo da chave primària.

O conteúdo das entidades relacionadas não pode ser criado / atualizado através deste mecanismo.

Stamp

Se um atributo __STAMP for dado, se realiza uma comprovação com o selo no armazén de dados e se pode devolver um erro ("O selo dado não coincide com o atual para o registro# XX da tabela XXXX"). Para saber mais, consulte Entity locking.

settings

No parâmetro querySettings é possível passar um objeto que conteha opções adicionais. As propriedades abaixo são compatíveis:

Propriedade	Tipo	Descrição
context	Text	Etiqueta para o contexto de otimização aplicado a seleção de entidades. Este contexto será utilizado pelo código que maneja a seleção de entidades para que possa se beneficiar da otimização. Essa funcionalidade foi criada para processamento cliente/servidor de ORDA .

Exemplo 1

Queremos atualizar uma entidade existente. A propriedade __NEW não for dada, a chave primária do empregado é dada e existe:

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs. EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.ID:=668 //Existing PK in Employee table
 $emp.firstName:="Arthur"
 $emp.lastName:="Martin"
 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company
  // For this employee, we can change the Company by using another existing PK in the related dataClass Company
 $empsCollection.push($emp)
 $employees:=ds. Employee.fromCollection($empsCollection)

Exemplo 2

Queremos atualizar uma entidade existente. A propriedade __NEW não é dada, a chave primária do empregado com o atributo __KEY e existir:

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs. EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.__KEY:=1720 //Existing PK in Employee table
 $emp.firstName:="John"
 $emp.lastName:="Boorman"
 $emp.employer:=New object("ID";121) //Existing PK in the related dataClass Company
  // For this employee, we can change the Company by using another existing PK in the related dataClass Company
 $empsCollection.push($emp)
 $employees:=ds. Employee.fromCollection($empsCollection)

Exemplo 3

Se quiser simplesmente criar uma nova entidade da coleção::

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs. EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.firstName:="Victor"
 $emp.lastName:="Hugo"
 $empsCollection.push($emp)
 $employees:=ds. Employee.fromCollection($empsCollection)

Exemplo

Queremos criar uma entidade. A propriedade __NEW é True, a chave primária de empregado não é dada:

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs. EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.firstName:="Mary"
 $emp.lastName:="Smith"
 $emp.employer:=New object("__KEY";121) //Existing PK in the related dataClass Company
 $emp.__NEW:=True
 $empsCollection.push($emp)
 $employees:=ds. Employee.fromCollection($empsCollection)

Exemplo 2

Queremos criar uma entidade. Se a propriedade __NEW é omitida, a chave primária do empregado é dada e não existir:

 var $empsCollection : Collection
 var $emp : Object
 var $employees : cs. EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.ID:=10000 //Unexisting primary key
 $emp.firstName:="Françoise"
 $emp.lastName:="Sagan"
 $empsCollection.push($emp)
 $employees:=ds. Employee.fromCollection($empsCollection)

Exemplo 6

Neste exemplo, a primeira entidade se criará e salvará mas a segunda falhará já que ambas utilizam a mesma chave primaria:

 var $empsCollection : Collection
 var $emp; $emp2 : Object
 var $employees : cs. EmployeeSelection

 $empsCollection:=New collection
 $emp:=New object
 $emp.ID:=10001 // Unexisting primary key
 $emp.firstName:="Simone"
 $emp.lastName:="Martin"
 $emp.__NEW:=True
 $empsCollection.push($emp)

 $emp2:=New object
 $emp2.ID:=10001 // Same primary key, already existing
 $emp2.firstName:="Marc"
 $emp2.lastName:="Smith"
 $emp2.__NEW:=True
 $empsCollection.push($emp2)
 $employees:=ds. Employee.fromCollection($empsCollection)
  //first entity is created
  //duplicated key error for the second entity

Veja também

.toCollection()

.get()

Histórico

Versão	Mudanças
v17	Adicionado

.get( primaryKey : Integer { ; settings : Object } ) : 4D. Entity
.get( primaryKey : Text { ; settings : Object } ) : 4D.

Parâmetro	Tipo		Descrição
primaryKey	Integer OR Text	->	Valor da chave primária da entidade a recuperar
settings	Objeto	->	Opção de construção: context
Resultados	4D. Entity	<-	Entidade que coincide com a chave primária designada

|

Descrição

A função .get() consulta a folha de dados para recuperar a entidade que corresponde ao parâmetro primaryKey.

Em primaryKey, passe o valor da chave primária da entidade a recuperar. Em primaryKey, passe o valor da chave primária da entidade a recuperar Em primaryKey, passe o valor da chave primária da entidade a recuperar O tipo valor deve coresponder com o tipo de chave primária estabelecido na datastore (Inteiro ou texto). Também pode se assegurar que o valor de chave primária seja sempre retornado como Texto ao usar a função .getKey() com o parâmetrodk key as string.

Se nenhuma entidade for encontrada com primaryKey, uma entidadeNull é retornada.

É aplicado o lazy loading/carregamento diferido, ou seja os dados relacionados são carregados do disco só quando pedidos.

settings

No parâmetro querySettings é possível passar um objeto que conteha opções adicionais. As propriedades abaixo são compatíveis:

Propriedade	Tipo	Descrição
context	Text	Etiqueta para o contexto de otimização automático aplicados à entidade. Esse contexto será usado pelo código subsequente que carrega a entidade para que se possa beneficiar da otimização. Essa funcionalidade foi criada para processamento cliente/servidor de ORDA .

Exemplo 1

 var $entity : cs. EmployeeEntity  
 var $entity2 : cs. InvoiceEntity
 $entity:=ds. Employee.get(167) // return the entity whose primary key value is 167
 $entity2:=ds. Invoice.get("DGGX20030") // return the entity whose primary key value is "DGGX20030"

Exemplo 2

Este exemplo ilustra o uso da propriedade context :

 var $e1; $e2; $e3; $e4 : cs. EmployeeEntity
 var $settings; $settings2 : Object

 $settings:=New object("context";"detail")
 $settings2:=New object("context";"summary")

 $e1:=ds. Employee.get(1;$settings)
 completeAllData($e1) // In completeAllData method, an optimization is triggered and associated to context "detail"

 $e2:=ds. Employee.get(2;$settings)
 completeAllData($e2) // In completeAllData method, the optimization associated to context "detail" is applied

 $e3:=ds. Employee.get(3;$settings2)
 completeSummary($e3) //In completeSummary method, an optimization is triggered and associated to context "summary"

 $e4:=ds. Employee.get(4;$settings2)
 completeSummary($e4) //In completeSummary method, the optimization associated to context "summary" is applied

.getDataStore()

Histórico

Versão	Mudanças
v17 R5	Adicionado

.getInfo() : Objeto

Parâmetro	Tipo		Descrição
Resultados	cs. DataStore	<-	Informação da dataclass

|

Descrição

The .getDataStore( ) function cria uma nova selecção de entidade, em branco e não partilhável, relacionada com o dataclass, em memória.

A datastore pode ser:

• a datastore principal, retornada pelo comando ds.
• uma datastore remota, aberta com o comando Open datastore.

Exemplo

O método de projeto SearchDuplicate procura por valores duplicados em qualquer dataclass.

 Pode usar parêntesis na pesquisa para dar prioridade ao cálculo Por exemplo, pode organizar uma pesquisa da seguinte maneira: Por exemplo, pode organizar uma pesquisa da seguinte maneira:

  // Pesquisa SearchDuplicate
  // SearchDuplicate(entity_to_search;dataclass_name)

 #DECLARE ($pet : Object ; $dataClassName : Text)
 var $dataStore; $duplicates : Object  

 $dataStore:=$pet.getDataClass().getDataStore()
 $duplicates:=$dataStore[$dataClassName].query("name=:1";$pet.name)

.getInfo()

Histórico

Versão	Mudanças
v17 R5	Adicionado

.getInfo() : Objeto

Parâmetro	Tipo		Descrição
Resultados	Objeto	<-	Datastore da dataclass

|

Descrição

The .getInfo( ) function devolve um objecto que fornece informação sobre o dataclass. Esta função é útil para configurar o código genérico.

Objeto devolvido

Propriedade	Tipo	Descrição
name	Text	Nome da dataclass
primaryKey	Text	Nome da chave primária da classe de dados
tableNumber	Integer	Número daa tabela 4D interna

Exemplo 1

 #DECLARE ($entity : Object)  
 var $status : Object

 computeEmployeeNumber($entity) //faz uma ação na entidade

 $status:=$entity.save()
 if($status.success)
    ALERT("Record updated in table "+$entity.getDataClass().getInfo().name)
 End if

Exemplo 2

 var $settings : Object
 var $es : cs. ClientsSelection

 $settings:=New object
 $settings.parameters:=New object("receivedIds";getIds())
 $settings.attributes:=New object("pk";ds. Clients.getInfo().primaryKey)
 $es:=ds. Clients.query(":pk in :receivedIds";$settings)

Exemplo 3

 var $pk : Text
 var $dataClassAttribute : Object

 $pk:=ds. Employee.getInfo().primaryKey
 $dataClassAttribute:=ds. Employee[$pk] // If needed the attribute matching the primary key is accessible

.new()

Histórico

Versão	Mudanças
v17	Adicionado

.new() : 4D. Entity

Parâmetro	Tipo		Descrição
Resultados	4D. Entity	<-	Nova entidade que coincide com a classe de dados

|

Descrição

The .new( ) function cria em memória e devolve uma nova entidade em branco relacionada com a Dataclass.

O objeto entidade se cria em memória e não se guarda no banco de dados até que se chama a função .save( ). Se a entidade for apagada antes de ser salva, não se pode recuperar.

4D Server: eám cliente-servidor, se a chave primaria da tabela correspondente se autoincrementa, se calculará quando a entidade se guarde no servidor.

Exemplo

Este exemplo cria uma nova entidade na classe de dados "Log" e registra a informação no atributo "info":

 var $entity : cs. LogEntity
 $entity:=ds. Log.new() //create a reference
 $entity.info:="New entry" //store some information
 $entity.save() //save the entity

.newSelection()

Histórico

Versão	Mudanças
v17	Adicionado

.newSelection( { keepOrder : Integer } ) : 4D. EntitySelection

Parâmetro	Tipo		Descrição
keepOrder	Integer	->	dk keep ordered: cria uma seleção de entidades ordenada, dk non ordered: cria uma seleção de entidade não ordenada (padrão se omitido)
Resultados	4D. EntitySelection	<-	Nova seleção de entidades em branco relacionadas com a classe de dados

|

Descrição

The .newSelection( ) function cria uma nova selecção de entidade, em branco e não partilhável, relacionada com o dataclass, em memória.

Para mais informação sobre as seleçõees de entidades não compartilháveis, consulte esta seção.

Se quiser uma seleção de entidades ordenada, passe o seletor dk keep ordered no parâmetro keepOrder. Como padrão se omitir este parâmetro ou se passar o seletor dk non ordered, o método cria uma seleção de entidades não ordenada. As seleções de entidades desordenadas são mais rápidas mas não se pode confiar nas posições das entidades. Para mas informação, consulte Seleções de entidades ordenadas e desordenadas.

Quando for criada, a seleção de entidades não contém nenhuma entidade (mySelection.length devolve 0). Este método lhe permite criar seleções de entidades gradualmente fazendo chamadas posteriores à função add().

Exemplo

 var $USelection; $OSelection : cs. EmployeeSelection
 $USelection:=ds. Employee.newSelection() //create an unordered empty entity selection
 $OSelection:=ds. Employee.newSelection(dk keep ordered) //create an ordered empty entity selection

.query()

Histórico

Versão	Mudanças
v17 R6	Soporte dos Parâmetros Formula
v17 R5	Suporte dos marcadores para os valores
v17	Adicionado

.query( queryString : Text { ; ...value : any } { ; querySettings : Object } ) : 4D. EntitySelection
.query( formula : Object { ; querySettings : Object } ) : 4D. EntitySelection

Parâmetro	Tipo		Descrição
queryString	Text	->	Criterios de pesquisa como string
formula	Objeto	->	Criterios de pesquisa como objeto fórmula
value	any	->	Valores a usar para placeholders indexados
querySettings	Objeto	->	Opções de pesquisa: parâmetros, atributos, args, allowFormulas, contexto, queryPath,queryPlan
Resultados	4D. EntitySelection	<-	Nova seleção de entidade feita de entidades de dataclass realizano o critério de pesquia especificado em queryString or formula

|

Descrição

The .query( ) function pesquisa por entidades que satisfaçam os critérios de pesquisa especificados em queryString ou fórmula e (opcionalmente) valor(s), para todas as entidades no dataclass, e devolve um novo objecto do tipo EntitySelection contendo todas as entidades que são encontradas. Se aplica carregamento diferido/lazy loading.

Se não houver entidades correspondentes encontradas, uma EntitySelection vazia é retornada.

parâmetro queryString

O parâmetro queryString usa a sintaxe abaixo:

attributePath|formula comparator value   
 {logicalOperator attributePath|formula comparator value}   
 {order by attributePath {desc | asc}}

onde:

• attributePath: caminho de atributo no qual se pretende executar a consulta. Os atributos se expressam como pares propriedade/ valor, onde propriedade é o nome do marcador de posição inserido para uma rota de atributo em queryString ou formula (":placeholder") e valor pode ser uma string ou uma coleção de strings. Cada valor e uma rota que pode designar um escalar ou um atributo relacionado da dataclass ou uma propriedade num campo de objeto da dataclass You can also use a placeholder (see below).

  Não pode usar diretamente atributos cujo nome contenha caracteres especiais como ".", "[ ]", or "=", ">", "#"..., porque serão avaliados incorretamente na string da query. Se precisar de uma query com esses atributos, deve considerar o uso de placeholders que permitem uma gama estendida de caracteres em rotas de atributo (ver Using placeholders below).

• formula: uma fórmula válida passada como Text ou Object. A fórmula será avaliada para cada entidade processada e deve retornar um valor booleano. Dentro da fórmula, a entidade está disponível através do objeto This.

  • Text: A string de fórmula deve ser precidida da declaração eval( ),para que o parser da pesquisa avalie a expressão corretamente. Por exemplo: "eval(length(This.lastname) >=30)"

  • Object: o objeto formula é passado como um placeholder (ver abaixo). A fórmula deve ter sido criada usando Formula ou o comandoFormula from string command.

    • • • Keep in mind that 4D formulas only support & and | symbols as logical operators.

    • Se a fórmula não for o único critério de pesquisa, o otimizador de motor debusca poderia processar outros critérios previamente (por exemplo atributos indexados) e assim, a fórmula poderia ser avaliada apenas para um subconjunto de entidades.

    Fórmulas nas consultas podem receber parâmetros através de $1. Este ponto é detalhado no parágrafo Parâmetro fórmula mais abaixo.

    • Também pode passar diretamente um objeto parâmetro formula ao invés do parâmetro queryString (recomendado quando as fórmulas sejam mais complexas). Ver o parágrafo Parâmetro fórmula mais abaixo.
    • For security reasons, formula calls within query() methods can be disallowed. Veja a descrição do parâmetro querySettings.

• comparator: symbol que compara attributePath e valor. Os simbolos abaixo são compatíveis:

  Comparação	Símbolos	Comentário
  Igual a	=, ==	Retorna os dados coincidentes, admite o coringa (@), não diferencia entre maiúsculas e minúsculas nem diacríticas.
  	===, IS	Retorna os dados coincidentes, considera @ como caractere padrão, não diferencia entre maiúsculas e minúsculas nem diacríticas
  Diferente de	#, !=	Suporta o coringa (@)
  	!==, IS NOT	Considera @ como um caractere normal
  Menor que	<
  Maior que	>
  Menor que ou igual a	<=
  Maior ou igual a	>=
  Incluído em	IN	Retorna dados iguais a ao menos um dos valores de uma coleção ou de um conjunto de valores, admite o coringa (@)
  Não se aplica à condição de uma sentença	NOT	Parentesis são obrigatórios quando usar NOT antes de uma instrução que contenha vários operadores
  Contém palavra chave	%	As palavras chaves podem ser usadas em atributos de string ou imagem

• value: o valor a comparar ao valor atual da propriedade de cada entidade na seleção de entidade ou elemento na coleção. Pode ser um marcador (ver Uso de marcadores mais adiante) ou qualquer expressão que coincida com a propriedad de tipo de dados. Quando usar um valor constante, as regras abaixo devem ser respeitadas:

  • A constante de tipo texto pode ser passada com ou sem aspas simples (ver Uso de aspas mais abaixo). Para pesquisar uma stirng dentro de uma string (uma pesquisa "contém") use o símbolo coringa (@) em valor para isolar a string a ser pesquisada como mostrado neste exemplo: "@Smith@". As palavras chaves abaixo são proibidas para constantes de texto: true, false.
  • Valores constantes de tipo booleano : true ou false (diferencia maiuscula de minúscula).
  • Valores constantes de tipo numérico: os decimais se separam com um '.' (ponto). date type constants: "YYYY-MM-DD" format
  • null constante: usando a palavra chave "null" encontra as propriedades null e undefined.
  • in case of a query with an IN comparator, value must be a collection, or values matching the type of the attribute path between [ ] separated by commas (for strings, " characters must be escaped with "\").

• logicalOperator: utilizado para unir condições múltiplas na pesquisa (opcional). Pode usaar um dos operadores lógicos abaixo (ou o nome ou o símbolo podem ser usados):

  Conjunção	Símbolos
  AND	&, &&, and
  OU	|,||, or

• order by attributePath: pode incluir uma declaração order by attributePath na pesquisa para que os dados resultantes sejam ordenados de acordo com esta declaração. Pode utilizar várias instruções de ordenação, separadas por vírgulas (por exemplo, ordenação por attributePath1 desc, attributePath2 asc). Como padrão, a ordem é ascendente. Passe 'desc'' para definir uma ordem descendente e 'asc' para definir uma ordem ascendente.

  *If you use this statement, the returned entity selection is ordered (for more information, please refer to Ordered vs Unordered entity selections).

Usar aspas

Quando usar aspas com pesquisas, deve usar aspas simples ' ' dentro das pesquisas e aspas duplas " " para cercar a consulta inteira, senão um erro é retornado. Por exemplo:

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

Aspas siples (') não são permitidas nos valores pesquisados, já que quebrariam a string de pesquisa. Por exemplo, "comp.name = 'John's pizza' " gerará um erro. Se precisar pesquisar valores com aspas simples, pode considerar o uso de placeholders (ver abaixo).

Usando parêntesis

É possível utilizar parênteses na consulta para dar prioridade ao cálculo. Por exemplo, pode organizar uma pesquisa da seguinte maneira:

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

Uso de placeholders

4D lhe permite utilizar placeholders, marcadores de posição, para os argumentos attributePath, formula e value dentro do parâmetro queryString. Um placeholder é um parâmetro que é inserido em strings de pesquisa e que pode ser substituído por outro valor quando a string for realizada. O valor dos placeholders é avaliado uma vez ao inicio da pesquisa - não é avaliado para cada elemento.

Dois tipos de marcadores podem ser usados: placeholders indexados e placeholders nomeados:

-	Marcadores de posição indexados	Placeholders nomeados
Definição	Parameters are inserted as :paramIndex (for example :1, :2...) in queryString and their corresponding values are provided by the sequence of value parameter(s). You can use up to 128 value parameters	Parameters are inserted as :paramName (for example :myparam) and their values are provided in the attributes and/or parameters objects in the querySettings parameter
Exemplo	$r:=class.query(":1=:2";"city";"Chicago")	$o.attributes:=New object("att";"city") $o.parameters:=New object("name";"Chicago") $r:=class.query(":att=:name";$o)

Pode misturar os tipos de argumentos em queryString. Um queryString pode conter, para os parâmetros attributePath, formula e value :

• valores diretos (sem marcadores),
• marcadores indexados ou com nome.

Using placeholders in queries is recommended for the following reasons:

1. Evita a inserção de código malicioso: se user diretamente variáveis preenchidas com uma string de pesquisa, um usuário poderia modificar as condições de pesquisa entrando argumentos adicionais. Por exemplo, imagine uma string de pesquisa como:

    $vquery:="status = 'public' & name = "+myname //o usuário introduz seu nome
    $result:=$col.query($vquery)

   Esta pesquisa parece segura já que se filtram os dados não públicos. Entretanto, se o usuário introduzr na área myname algo como "smith OR status='private', a string de pesquisa se modificaría na etapa da interpretação e poderia devolver dados privados.

   Quando usar marcadores de posição, não é possível anular as condições de segurança:

    $result:=$col.query("status='public' & name=:1";myname)

   Neste caso, se o usuário introduz smith OR status='private' na área myname, não se interpretará na string de pesquisa, só será passada como um valor. Procurando por "smith OR status = 'private' vai falhar

2. Evita ter que se preocupar por questões de formato ou caracteres, especialmente quando se manejam os parâmetros attributePath o value que podem conter não alfanuméricos como ".", "['...

3. Permite o uso de variáveis ou expressões nos argumentos de pesquisa. Exemplos:

    $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
   $result2:=$col.query("company.name = :1";"John's Pizzas")

Pesquisa de valores null

Quando pesquisar por valores null não pode usar a sintaxe de placeholder porque o motor de pesquisa vai consider null como um valor de comparação inesperado. Por exemplo se executar esta pesquisa:

$vSingles:=ds. Person.query("spouse = :1";Null) // will NOT work

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

 $vSingles:=ds. Person.query("spouse = null") //correct syntax

Linkar os argumentos de pesquisa com os atributos de coleção

info

Esta funcionalidade só está disponível em consultas de dataclasses e selecção de entidades. Não pode ser utilizado em pesquisas em colecções.

Para fazer isso, é necessário vincular os argumentos de pesquisa para elementos de coleção, para que apenas elementos únicos contendo argumentos linkados são encontrados. Ao pesquisar dentro de atributos de objectos dataclass contendo colecções utilizando múltiplos argumentos de consulta unidos pelo operador AND, poderá querer certificar-se de que apenas entidades contendo elementos que correspondem a todos os argumentos são devolvidas, e não entidades onde os argumentos podem ser encontrados em diferentes elementos.

Por exemplo, com as duas entidades abaixo:

Entity 1:
ds. People.name: "martin"
ds. People.places:
    { "locations" : [ {
                "kind":"home",
                "city":"paris"
            } ] } Entity 2:
ds. People.name: "smith"
ds. People.places:
    { "locations" : [ {
                "kind":"home",
                "city":"lyon"
            } , {
                "kind":"office",
                "city":"paris"
            } ] }

Se quiser encontrar pessoas com um tipo de local "home" na cidade "paris". Se escrever

ds. People.query("places.locations[].kind= :1 and places.locations[].city= :2";"home";"paris")

... a pesquisa devolverá "martin" e "smith" porque "smith" tem um elemento "locations" cujo "tipo" é "home" e um elemento "locations" cuja "cidade" é "paris", mesmo que sejam elementos diferentes.

Se quiser obter apenas entidades onde os argumentos correspondentes estão no mesmo elemento coleção, precisa linkar os argumentos. Para linkar argumentos de pesquisa:

• Adicionar uma letra entre os [] na primeira rota a linkar e repita a mesma letra em todos os argumentos linkados. Por exemplo: locations[a].city and locations[a].kind. Pode usar qualquer letra do alfabeto latino (não diferencia maiúsculas e minúsculas).
• Para adicionar critérios linkados na mesma pesquisa, use outra letra. Pode criar até 26 combinações de critérios em uma única pesquisa.

Com as entidades acima, se escreve:

ds. People.query("places.locations[a].kind= :1 and places.locations[a].city= :2";"home";"paris")

... pesquisa só devolverá "martin" porque tem um elemento "locations" cujo "kind" é "home" e cujo "city" for "paris". A pesquisa não devolverá 'smith' porque os valores 'home' e 'paris' não estão no mesmo elemento de coleção.

parâmetro de fórmula

Como alternativa à inserção de fórmulas dentro do parâmetro queryString (ver acima), pode passar diretamente um objeto fórmula como critério de pesquisa booleano. A utilizaçã de um objeto fórmula para as pesquisas é recomendada já que se beneficia da tokenização, e o código é mais fácil de pesquisar/ler.

The formula must have been created using the Formula or Formula from string command. Nesse modo:

• fórmula se avalia para cada entidade e deve devolver true ou false. Durante a execução da pesquisa, se o resultado da fórmula não for booleano, é considerado como False.
• dentro da fórmula, a entidade está disponível através do objeto This.
• if the Formula object is null, the errror 1626 ("Expecting a text or formula") is generated, that you call intercept using a method installed with ON ERR CALL.

  For security reasons, formula calls within query() member methods can be disallowed. Veja a descrição do parâmetro querySettings.

Passar parâmetros a fórmulas

Todo parâmetro formula chamado pela função query() pode receber parâmetros:

• Parâmeters devem ser passados através da propriedade args (objeto) do parâmetro querySettings.
• A fórmula recebe este objeto args como um parâmetro $1.

Este pequeno código mostra os principios de como são passados os parâmetros aos métodos:

 $settings:=New object("args";New object("exclude";"-")) //args object to pass parameters
 $es:=ds. Students.query("eval(checkName($1.exclude))";$settings) //args is received in $1

No exemplo 3 são oferecidos mais exemplos.

4D Server: em cliente/servidor, as fórmulas são executadas no servidor. Neste contexto, só se envia às fórmulas o objeto querySettings.args.

parâmetro querySettings

No parâmetro querySettings é possível passar um objeto que conteha opções adicionais. As propriedades abaixo são compatíveis:

Propriedade	Tipo	Descrição
parameters	Objeto	Marcadores nomeados para os valores utilizados em queryString ou fórmula. Os valores se expressam como pares propriedade / valor, onde propriedade é o nome do marcador de posição inserido para um valor em queryString ou formula (":placeholder") e valor é o valor a comparar. Pode combinar marcadores de posição indexados (valores passados diretamente em parâmetros de valor) e valores de marcadores de posição com nome na mesma pesquisa.
attributes	Objeto	attributePath: path of attribute on which you want to execute the query. Os atributos se expressam como pares propriedade/ valor, onde propriedade é o nome do marcador de posição inserido para uma rota de atributo em queryString ou formula (":placeholder") e valor pode ser uma string ou uma coleção de strings. Cada valor e uma rota que pode designar um escalar ou um atributo relacionado da dataclass ou uma propriedade num campo de objeto da dataclass Tipo Descrição String attributePath expressado com a notação de pontos, por exemplo: "name" ou "user.address.zipCode" Coleção de strings Cada string da coleção representa um nível de attributePath, por exemplo: ["name"] ou ["user","address","zipCode"]. Usar uma coleção permite pesquisar atributos com nomes que não se ajustem à notação de pontos, por exemplo ["4Dv17.1","en/fr"] Pode combinar marcadores de posição indexados (valores passados diretamente nos parâmetros value) e os valores de marcadores de posição com nome na mesma pesquisa.
args	Objeto	Parámetro(s) a passar para as fórmulas, se houver. O objeto args será recebido em $1 dentro das fórmulas e, portanto, seus valores estarão disponíveis através de $1.property (ver exemplo 3).
allowFormulas	Parâmetros	True para permitir as chamadas de fórmulas na pesquisa (padrão). Passe falso para desautorizar a execução de fórmulas. Se for estabelecido como false y query() receber uma fórmula, se envia um erro (1278 - Fórmula não permitida neste método membro).
context	Text	Etiqueta para o contexto de otimização automático aplicados à seleção de entidade. Este contexto será utilizado pelo código que maneja a seleção de entidades para que possa se beneficiar da otimização. Esta função está projetada para o processamento cliente/servidor; para saber mais, consulte Otimização cliente/servidor.
queryPlan	Parâmetros	Na entity selection resultante, devolve ou não a descrição detalhada da pesquisa logo antes de ser executada, ou seja, a pesquisa planificada. A propriedade devolvida é um objeto que inclui cada pesquisa e subpesquisa prevista (no caso de uma pesquisa complexa). Esta opção é útil durante a fase de desenvolvimento de uma aplicação. Geralmente é usada em conjunto com queryPath. Como padrão é omitido: false. Note: This property is supported only by the entitySelection.query( ) and dataClass.query( ) functions.
queryPath	Parâmetros	Na entity selection resultante, devolve ou não a descrição detalhada da pesquisa tal qual for realizada. A propriedade retornada é um objeto que contém a rota atual usada para a pesquisa (geralmente idêntica àquela do queryPlan, mas deve diferenciar se o motor consegue otimizar a pesquisa), assim como o tempo de processamento e o número de registros encontrado. Esta opção é útil durante a fase de desenvolvimento de uma aplicação. Como padrão é omitido: false. Note: This property is supported only by the entitySelection.query( ) and dataClass.query( ) functions.

Sobre queryPlan e queryPath

A informação registrada em queryPlan/queryPath inclui o tipo de pesquisa (indexada e sequencial) e cada subconsulta necessária junto com os operadores de conjunção. As rotas de acesso das petições também contém o número de entidades encontradas e o tempo necessário para executar cada critério de pesquisa. As rotas de acesso das petições também contém o número de entidades encontradas e o tempo necessário para executar cada critério de pesquisa. Geralmente a descrição do plano de pesquisa e sua rota são idênticas mas podem ser diferentes porque 4D pode implementar otimizações dinâmicas quando uma pesquisa for executada para melhorar a performance. Por exemplo, o motor 4D pode converter dinamicamente uma consulta indexada em uma consulta sequencial se estimar que seja mais rápido. Esse caso particular pode acontecer quando o número de entidades sendo pesquisada é baixo.

Por exemplo se executar esta pesquisa:

 $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}]}]}]}]}

Exemplo 1

Esta seção oferece vários exemplos de pesquisas.

Consultas em uma string:

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

Consulta com uma instrução NOT:

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

Pesquisas com datas:

$entitySelection:=ds. Employee.query("birthDate > :1";"1970-01-01")
$entitySelection:=ds. Employee.query("birthDate <= :1";Current date-10950)

Pesquisa com marcadores de posição indexados para os valores:

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

Pesquisa com marcadores de posição indexados para valores em u ma dataclass relacionada:

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

Pesquisa com marcador de posição indexado que inclui uma instrução de ordem descendente:

$entitySelection:=ds. Student.query("nationality = :1 order by campus.name desc, lastname";"French")

Pesquisa com marcadores de posição com nome para os valores:

var $querySettings : Object
var $managedCustomers : cs. CustomerSelection
$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 marcadores de posição nomeados e indexados para valores:

var $querySettings : Object
var $managedCustomers : cs. CustomerSelection
$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))

  //you can then get these properties in the resulting entity selection
var $queryPlan; $queryPath : Object
$queryPlan:=$entitySelection.queryPlan
$queryPath:=$entitySelection.queryPath

Pesquisa com uma rota de atributo de tipo Collection:

$entitySelection:=ds. Employee.query("extraInfo.hobbies[].name = :1";"horsebackriding")

Pesquisa com uma rota de atributos de tipo Collection e atributos vinculados:

$entitySelection:=ds. Employee.query("extraInfo.hobbies[a].name = :1 and extraInfo.hobbies[a].level=:2";"horsebackriding";2)

Pesquisa com uma rota de atributos de tipo Collection e múltiplos atributos vinculados:

$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 Objeto

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

Pesquisa com uma instrução IN:

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

Pesquisa com instrução NOT (IN):

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

Pesquisa com marcadores de posição indexados para os atributos:

var $es : cs. EmployeeSelection
$es:=ds. Employee.query(":1 = 1234 and :2 = 'Smith'";"salesperson.userId";"name")
  //salesperson is a related entity

Pesquisa com marcadores de posição indexados para os atributos e marcadores de posição com nome para os valores:

var $es : cs. EmployeeSelection
var $querySettings : Object
$querySettings:=New object
$querySettings.parameters:=New object("customerName";"Smith")
$es:=ds. Customer.query(":1 = 1234 and :2 = :customerName";"salesperson.userId";"name";$querySettings)
  //salesperson is a related entity

Pesquisa com marcadores de posição indexados para os atributos e os valores:

var $es : cs. EmployeeSelection
$es:=ds. Clients.query(":1 = 1234 and :2 = :3";"salesperson.userId";"name";"Smith")
  //salesperson is a related entity

Exemplo 2

Esta seção ilustra pesquisas com marcadores de posição com nomes para os atributos.

Dada uma dataclass Employee com 2 entidades:

Entidade 1:

name: "Marie"
number: 46
softwares:{
"Word 10.2": "Installed",
"Excel 11.3": "To be upgraded",
"Powerpoint 12.4": "Not installed"
}

Entidade 2:

name: "Sophie"
number: 47
softwares:{
"Word 10.2": "Not installed",
"Excel 11.3": "To be upgraded",
"Powerpoint 12.4": "Not installed"
}

Pesquisa com marcadores de posição com nome para os atributos:

 var $querySettings : Object
 var $es : cs. EmployeeSelection
 $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 marcadores de posição com nome para os atributos e os valores:

 var $querySettings : Object
 var $es : cs. EmployeeSelection
 var $name : Text
 $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

Exemplo 3

Estes exemplos ilustram as distintas formas de utilizar fórmulas com ou sem parâmetros em suas pesquisas.

A fórmula se da como texto com eval() no parâmetro queryString:

 var $es : cs. StudentsSelection
 $es:=ds. Students.query("eval(length(This.lastname) >=30) and nationality='French'")

A fórmula se dá como um objeto Formula através de um marcador de posição:

 var $es : cs. StudentsSelection
 var $formula : Object
 $formula:=Formula(Length(This.lastname)>=30)
 $es:=ds. Students.query(":1 and nationality='French'";$formula)

Só se da como criterio um objeto Formula:

 var $es : cs. StudentsSelection
 var $formula : Object
 $formula:=Formula(Length(This.lastname)>=30)
 $es:=ds. Students.query($formula)

Podem ser aplicadas várias fórmulas:

 var $formula1; $1; $formula2 ;$0 : Object
 $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:

 var $es : cs. StudentsSelection
 var $settings : Object
 $settings:=New object()
 $settings.args:=New object("filter";"-")
 $es:=ds. Students.query("eval(checkName($1.filter)) and nationality=:1";"French";$settings)

  //checkName method
 #DECLARE($exclude : Text) -> $result : Boolean
 $result:=(Position($exclude;This.lastname)=0)

Utilizando o mesmo método checkName, um objeto Formula como marcador de posição recebe um parámetro:

 var $es : cs. StudentsSelection
 var $settings; $formula : Object
 $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)

Queremos desautorizar as fórmulas, por exemplo, quando el usuario introduz sua consulta:

 var $es : cs. StudentsSelection
 var $settings : Object
 var $queryString : Text
 $queryString:=Request("Enter your query:")
 if(OK=1)
    $settings:=New object("allowFormulas";False)
    $es:=ds. Students.query($queryString;$settings) //An error is raised if $queryString contains a formula
 End if

Veja também

.query() para seleções de entidades