Edit

EntitySelection

Uma seleção de entidades é um objeto que contém uma ou mais referencias a entidades pertencentes à mesma Dataclass. Uma seleção de entidades pode conter 0, 1 ou X entidades da dataclass -- onde X pode representar o número total de entidades contidas na dataclass.

As seleções de entidades podem ser criadas a partir de seleções existentes utilizando varias funções da classe DataClass class tais como .all() ou .query(), ou da classe EntityClass mesma, tal como .and() ou orderBy(). Também pode criar seleções de entidades em branco utilizando a função dataClass.newSelection() ou o comando Create new selection.

Resumo

attributePath for um atributo relativo,
Se o "kind" de attributeName é storage: .attributeName devolve uma coleção de valores do mesmo tipo que attributeName.
attributePath não se encontra na classe de dados da entity selection.
.and( entity : 4D. Entity ) : 4D. EntitySelection .and( entitySelection : 4D. EntitySelection ) : 4D. EntitySelection
.average( {propertyPath : Text } ) : Real
attributePath for um atributo relativo,
.count( attributePath : Text ) : Real
.distinct( attributePath : Text { ; option : Integer } ) : Collection
.drop( { mode : Integer } ) : 4D. EntitySelection
.extract( attributePath : Text { ; option : Integer } ) : Collection .extract( attributePath { ; targetPath } { ; ...attributePathN : Text ; targetPathN : Text } ) : Collection     retorna una coleção que contenha os valores de attributePath extraídos da entity selection
.first() : 4D. Entity
.getDataClass() : 4D. DataClass
.isAlterable() : Boolean      devolve True se a entity selection for modificável
.isOrdered() : Boolean      devolve True se a entity selection for ordenada
.last() : 4D. Entity      devolve uma referência à entidad em última posição da entity selection
.length : Integer
.max( attributePath : Text ) : any     devolve o valor mais alto (ou máximo) entre todos os valores de attributePath na entity selection
.min( attributePath : Text ) : any      devolve i valor mais baixo (ou mínimo) entre todos os valores de attributePath na entity selection
.minus( entity : 4D.Entity ) : 4D.EntitySelection .minus( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection     excludes from the entity selection to which it is applied the entity or the entities of entitySelection and returns the resulting entity selection
.or( entity : 4D.Entity ) : 4D.EntitySelection .or( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection     combines the entity selection with the entity or entitySelection parameter using the logical (not exclusive) OR operator
.orderBy( pathString : Text ) : 4D.EntitySelection .orderBy( pathObjects : Collection ) : 4D.EntitySelection     devolve uma nova entity selection ordenada que contém todas as entidades da entity selection na ordem especificada pelos criterios pathString ou pathObjects
.orderByFormula( formulaString : Text { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection .orderByFormula( formulaObj : Object { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection     returns a new, ordered entity selection
.query( queryString : Text { ; ...value : any } { ; querySettings : Object } ) : 4D. EntitySelection .query( formula : Object { ; querySettings : Object } ) : 4D. EntitySelection     searches for entities that meet the search criteria specified in queryString or formula and (optionally) value(s) among all the entities in the entity selection
.queryPath : Text     contains a detailed description of the query as it was actually performed by 4D
.queryPlan : Text      contains a detailed description of the query just before it is executed (i.e., the planned query)
.refresh()     immediately "invalidates" the entity selection data in the local ORDA cache
.slice( startFrom : Integer { ; end : Integer } ) : 4D.EntitySelection     returns a portion of an entity selection into a new entity selection
.sum( attributePath : Text ) : Real     returns the sum for all attributePath values in the entity selection
.toCollection( { options : Integer { ; begin : Integer { ; howMany : Integer } } ) : Collection .toCollection( filterString : Text {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection .toCollection( filterCol : Collection {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection     creates and returns a collection where each element is an object containing a set of properties and values

Criar uma seleção de entidades (entity selection)

attributePath não se encontra na classe de dados da entity selection.

Parâmetros	Tipo		Descrição
dsTable	Tabela	->	Tabela do banco de dados 4D cuja seleção atual se utilizará para construir a seleção de entidades
settings	Objeto	->	Build option: context
Resultados	4D.EntitySelection	<-	Seleção de entidades que coincidem com a classe de dados relacionada com a tabela dada

Descrição

O comando Create entity selection constrói e devolve uma nova, alterável seleção de entidade relacionada com a classe de dados que coincide com a tabela dsTable dada, segundo a seleção atual desta tabela.

Se a seleção atual for ordenada, é criada uma seleção de entidades ordenada (se mantém a ordem da seleção atual). Se a seleção atual não for ordenada, se cria uma seleção de entidades não ordenada.

Se a tabela dsTable não estiver exposta em ds, se devolve um erro. Esse comando não pode usado com uma datastore remota.

No parâmetro opcionalsettings pode passar um objeto contendo as propriedades abaixo:

Propriedade	Tipo	Descrição
context	Texto	Etiqueta para contexto de optimização aplicado a entity selection.

Exemplo

var $employees : cs. EmployeeSelection ALL RECORDS([Employee])
$employees:=Create entity selection([Employee]) 
// A entity selection $employees agora contém um conjunto de referências
// em todas as entidades relacionadas com a classe de dados Employee

Veja também

dataClass.newSelection()

[index]

Histórico

Versão	Mudanças
v17	Adicionado

attributePath for um atributo relativo,

Descrição

A notação EntitySelection[index] permite acessar as entidades dentro da seleção de entidades utilizando a sintaxe de coleção padrão: passe a posição da entidade que quiser obter no parâmetro index.

Lembre que a entidade correspondente é recarregada a partir da datastore.

index pode ser qualquer número entre 0 e .length-1.

• Se index está fora do intervalo, se devolve um erro.
• Se index corresponde a uma entidade descartada, se devolve um valor Null.

Atenção: EntitySelection[index] é uma expressão não atribuível, o que significa que não pode utilizar-se como referência editável da entidade com métodos como .lock() o .save(). Para trabalhar com a entidade correspondente, é necessário atribuir a expressão devolvida a uma expressão atribuível, como uma variável. Exemplos:

 $sel:=ds. Employee.all() //criação da entity selection
  //declarações não válidas:
 $result:=$sel[0].lock() //NÃO funcionará
 $sel[0].lastName:="Smith" //NÃO funcionará
 $result:=$sel[0].save() //NÃO funcionará
  //valid code:
 $entity:=$sel[0]  //OK
 $entity.lastName:="Smith" //OK
 $entity.save() //OK

Exemplo

 var $employees : cs. EmployeeSelection
 var $employee : cs. EmployeeEntity
 $employees:=ds. Employee.query("lastName = :1";"H@")
 $employee:=$employees[2]  // A terceira entidade da seleção de entidades $employees se recarrega do banco de dados

.attributeName

Histórico

Versão	Mudanças
v17	Adicionado

Se o "kind" de attributeName é storage: .attributeName devolve uma coleção de valores do mesmo tipo que attributeName.

Descrição

As seleções de entidades podem ser criadas a partir de seleções existentes utilizando varias funções da classe DataClass class tais como .all() ou .query(), ou da classe EntityClass mesma, tal como .and() ou orderBy(). Também pode criar seleções de entidades em branco utilizando a função dataClass.newSelection() ou o comando Create new selection.

• Se o "kind" de attributeName é storage: .attributeName devolve uma coleção de valores do mesmo tipo que attributeName.
• Se o "kind" de attributeName for relatedEntity: .attributeName devolve uma nova entity selection de valores relacionados do mesmo tipo que attributeName. Se eliminam os duplicados (se devolve uma seleção de entidades desordenada).
• Se o "kind" de attributeName for relatedEntities: .attributeName devolve uma nova entity selection de valores relacionados do mesmo tipo que attributeName. Se eliminam os duplicados (se devolve uma seleção de entidades desordenada).

Quando se utiliza um atributo de relação como propriedade de uma seleção de entidades, o resultado é sempre outra seleção de entidades, mesmo que só se devolva uma entidade. If the original entity selection and the entitySelection parameter are empty, an empty entity selection is returned.

Se o atributo não existir na seleção de entidades, se devolve um erro.

Exemplo 1

Projeção de valores de armazenamento:

 var $firstNames : Collection
 $entitySelection:=ds. Employee.all()
 $firstNames:=$entitySelection.firstName // firstName é um string

A coleção resultante é uma coleção de strings, por exemplo:

[
    "Joanna",
    "Alexandra",
    "Rick"
]

Exemplo 2

Projeção da entidade relacionada:

 var $es; $entitySelection : cs. EmployeeSelection
 $entitySelection:=ds. Employee.all()
 $es:=$entitySelection.employer // employer é relacionada aum  Company dataClass

O objeto resultane é uma seleção de entidade da Empresa com duplicações removidas (se houver).

Exemplo 3

Projeção de entidades relacionadas:

 var $es : cs. EmployeeSelection
 $es:=ds. Employee.all().directReports // directReports é relacionada a dataclasse Funcionário

O objeto resultante é uma seleção de entidade da dataclasse Funcionario sem duplicatas (se houver).

.add()

Histórico

Versão	Mudanças
v18 R5	Compatível apenas com seleções de entidade alteráveis
v17	Adicionado

attributePath não se encontra na classe de dados da entity selection.

Parâmetros	Tipo		Descrição
entity	4D.Entity	->	Entidade que deve ser adicinonada à entity selection
Resultado	4D.EntitySelection	->	Seleção de entidades incluindo a entity adicionada

Descrição

A função .add() adiciona a entity especificada a entity selection e devolve a seleção de entidades modificada.

Os valores de tipo Date são convertidos em valores numéricos (segundos) e são usados para calcular a média.

Atenção: a entity selection deve ser alteravel, ou seja, foi criado por ejemplo, por .newSelection() ou Create entity selection, do contrário .add() devolverá um erro. As entity selections partilháveis não aceitam a adição de entidades. Para saber mais, consulte Entity selections compartilháveis ou modificáveis .

• Se a entity selection estiver ordenada, entity se adiciona ao final da seleção. Se uma referência a mesma entidade já pertencer a seleção de entidades, se duplica e se adiciona uma nova referência.
• Se a entity selection não estiver ordenada, entity se adiciona em qualquer lugar da seleção, sem uma ordem específica.

Para saber mais veja Entity selections ordenada ou não ordenadas.

A entity selection modificada é devolvida pela função, de modo que as chamadas à função podem ser encadeados.

Se produz um erro se entity e a entity selection não estão relacionadas com a mesma dataclass. Se entity for Null, não se produz nenhum erro.

Exemplo 1

 var $employees : cs. EmployeeSelection
 var $employee : cs. EmployeeEntity
 $employees:=ds. Employee.query("lastName = :1";"S@")
 $employee:=ds. Employee.new()
 $employee.lastName:="Smith"
 $employee.save()
 $employees.add($employee) //A entidade $employee se adiciona a entity selection $employees

Exemplo 2

As chamadas à função podem ser encadeadas:

 var $sel : cs. ProductSelection
 var $p1;$p2;$p3 : cs. ProductEntity

 $p1:=ds. Product.get(10)
 $p2:=ds. Product.get(11)
 $p3:=ds. Product.get(12)
 $sel:=ds. Product.query("ID > 50")
 $sel:=$sel.add($p1).add($p2).add($p3)

.and()

Histórico

Versão	Mudanças
v17	Adicionado

.and( entity : 4D. Entity ) : 4D. EntitySelection
.and( entitySelection : 4D. EntitySelection ) : 4D. EntitySelection

Parâmetros	Tipo		Descrição
entity	4D.Entity	->	Entidade a intersectar
entitySelection	4D.EntitySelection	->	Entity selection a intersectar
Resultados	4D.EntitySelection	<-	Entity selection resultante da intersecção com o operador lógico AND

Descrição

A função .and() combina a entity selection com o parâmetro entity ou entitySelection utilizando o operador lógico AND; devolve uma nova entity selection não ordenada que contém só as entidades às que se faz referência tanto na entity selection quanto o parâmetro.

• Se passar entity como parâmetro, se combina esta entidade com a entity selection. Se a entidade pertencer à entity selection, se devolve uma nova entity selection que só contém a entidade. Senão, uma seleção de entidades vazia é retornada.
• Se passar entitySelection como parâmetro, combina ambas entity selections. Uma nova seleção de entidades que contenha apenas as entidades que são referenciadas em ambas as seleções é retornada. Se não houver uma entidade intersectada, se devolve uma entity selection vazia:

Pode comparar entity selections ordenadas ou desordenadas. A seleção resultante é sempre desordenada.

Se a entity selection inicial ou o parâmetro entitySelection estiverem vazios, ou se entity for Null, se devolve uma entity selection vazia.

Se a entity selection inicial e o parâmetro não forem relacionados com a mesma dataclass, se produz um erro.

Exemplo 1

 var $employees; $notDropped : cs. EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop(dk stop dropping on first error) //$notDropped é uma entity selection que contém a primeira entidade não eliminada
 If($notDropped.length=0) //A ação de eliminação é exitosa, todas as entidades foram eliminadas
    ALERT("You have dropped "+String($employees.length)+" employees") //A seleção de entidades eliminada permanece na memória
 Else
    ALERT("Problem during drop, try later")
 End if

Exemplo 2

Se quisermos ter uma seleção de empregados chamados "Jones" que morem em Nova York:

 var $sel1; $sel2; $sel3 : cs. EmployeeSelection
 $sel1:=ds. Employee.query("name =:1";"Jones")
 $sel2:=ds. Employee.query("city=:1";"New York")
 $sel3:=$sel1.and($sel2)

.average()

Histórico

Versão	Mudanças
v18 R6	Retorna indefinido se uma seleção de entidade for vazia
v17	Adicionado

.average( {propertyPath : Text } ) : Real

Parâmetros	Tipo		Descrição
attributePath	Texto	->	Rota de atributo a utilizar para o cálculo
Resultado	Real	<-	Media aritmética (média) dos valores das entidades para o atributo (Não se define para uma entity selection vazia)

Descrição

attributePath designa um atributo que não existir na dataclass da entity selection.

Passe no parâmetro attributePath a rota de atributo a avaliar.

Só são levados em consideração os valores numéricos para o cálculo. Lembre entretanto que se o attributePath da seleção de entidades conter tipos de valores mistos, .average() considera todos os elementos escalares para calcular o valor médio.

Para saber mais sobre propriedade compartilhável de entity selections, consulte Entity selections compartilháveis ou modificáveis.

.average() returns undefinedse a entity selection estiver vazia ou attributePath não conter valores numéricos.

Um erro é retornado se:

• attributePath for um atributo relativo,
• attributePath designa um atributo que não existir na dataclass da entity selection.

Exemplo

Se quisermos obter uma lista de funcionários cujo salário for superior ao salário médio:

 var $averageSalary : Real
 var $moreThanAv : cs. EmployeeSelection
 $averageSalary:=ds. Employee.all().average("salary")
 $moreThanAv:=ds. Employee.query("salary > :1";$averageSalary)

.contains()

Histórico

Versão	Mudanças
v17	Adicionado

attributePath for um atributo relativo,

Parâmetros	Tipo		Descrição
entity	4D.Entity	->	Entidade a ser avaliada
Resultado	Booleano	<-	Truse se a entidade pertencer à entity selection, senão False

Descrição

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

Em entity, especifique a entidade a buscar na entity selection. Se a entidade for Null, a função devolverá false.

Se entity e a entity selection não pertencerem à mesma dataclass, se produz um erro.

Exemplo

 var $employees : cs. EmployeeSelection
 var $employee : cs. EmployeeEntity

 $employees:=ds.Employee.query("lastName=:1";"H@")
 $employee:=ds. Employee.get(610)

 If($employees.contains($employee))
    ALERT("A entidade com chave primaria 610 tem um sobrenome começando com H")
 Else
    ALERT("A entidade com chave primária 610 não tem um sobrenome começando com H")
 End if

.count()

Histórico

Versão	Mudanças
v17	Adicionado

.count( attributePath : Text ) : Real

Parâmetros	Tipo		Descrição
attributePath	Texto	->	Rota do atributo que se utilizará para o cálculo
Resultado	Real	<-	Número de valores de attributePath que não são null na entity selection

Descrição

attributePath for um atributo relativo,

Só são levados em consideração os valores escalares. Os valores de tipo objeto ou coleção são considerados valores nulos.

Um erro é retornado se:

• attributePath for um atributo relativo,
• attributePath não se encontra na classe de dados da entity selection.

Exemplo

Se quisermos encontrar o número total de empregados para uma empresa sem contar aqueles cujos titulos de mprego não foram especificados:

 var $sel : cs. EmployeeSelection
 var $count : Real

 $sel:=ds. Employee.query("employer = :1";"Acme, Inc")
 $count:=$sel.count("jobtitle")

.copy()

Histórico

Versão	Mudanças
v18 R5	Adicionado

.copy( { option : Integer } ) : 4D. EntitySelection

Parâmetros	Tipo		Descrição
option	Integer	->	ck shared: devolve uma entity selection compartilhável
Resultado	4D. EntitySelection	<-	Cópia da entity selection

Descrição

A função .copy() devolve uma cópia da entity selection original.

Esta função não modifica a entity selection original.

Como padrão, se omitir o parámetro option, a função devolve uma nova entity selection alterável (mesmo se a função se aplicar a uma entity selection compartilhável). Passe a constante ck shared no parâmetro option se quiser criar uma entity selection compartilhável.

Para saber mais sobre propriedade compartilhável de entity selections, consulte Entity selections compartilháveis ou modificáveis.

Exemplo

Se criar uma nova seleção de entidade vazia de produtos quando o formulário for carregado:

 Case of
    :(Form event code=On Load)
       Form.products:=ds. Products.newSelection()
 End case

Então esta seleção de entidades é atualizada com produtos e se quiser compartilhar os produtos entre vários processos. Se copiar a seleçãod a entidade Form.products como compartilhável:

 ...
  // A seleção de entidades de Form.products se atualiza
 Form.products.add(Form.selectedProduct)

 Use(Storage)
    If(Storage.products=Null)
       Storage.products:=New shared object()
    End if

    Use(Storage.products)
       Storage.products:=Form.products.copy(ck shared)
    End use
 End use

.distinct()

Histórico

Versão	Mudanças
v17	Adicionado

.distinct( attributePath : Text { ; option : Integer } ) : Collection

Parâmetros	Type		Descrição
attributePath	Texto	->	Rota do atributo cujos valores quer obter
option	Integer	->	dk diacritical: avaliação diacríticos ("A" # "a" por exemplo)
Resultado	Coleção	<-	Coleção apenas com valores distintos

Descrição

A função .distinct() retorna uma coleção contendo apenas valores distintos (diferentes) da attributePath na entity selection.

A coleção retornada é ordenada automaticamente. Valores Null não são retornados.

No parámetro attributePath, passe o atributo de entidade cujos valores distintos queira obter. Só valores escalares (texto, número, booleano, ou data) podemser manejados. Tipos são retornados na ordem abaixo: Se attributePath levar a uma propriedade de objeto que conter valores de diferentes tipos, primeiro se agrupam por tipo e se ordenam depois.

1. booleans
2. strings
3. números
4. datas

Pode utilizar a notação [] para designar uma coleção quando attributePath for uma rota dentro de um objeto (ver exemplos).

Como padrão, uma avaliação não-diacrítica é realizada. Se quiser que a avaliação diferencie minúsculas de maiúsculas ou que diferencie letras acentuadas, passe a constante dk diacritical no parâmetrooption.

Um erro é retornado se:

• attributePath for um atributo relativo,
• attributePath não se encontra na classe de dados da entity selection.

Exemplos

Se quiser obter uma coleção que contenha um só elemento por nome de país:

 var $countries : Collection
 $countries:=ds. Employee.all().distinct("address.country")

nicknames é uma coleção e extra for um atributo de objeto:

$values:=ds. Employee.all().distinct("extra.nicknames[].first")

.drop()

Histórico

Versão	Mudanças
v17	Adicionado

.drop( { mode : Integer } ) : 4D. EntitySelection

Parâmetros	Tipo		Descrição
mode	Integer	->	dk stop dropping on first error: para a execução do método na primeira entidade não eliminável
Resultado	4D.EntitySelection	<-	Entidade de seleção vazia se for executada com êxito, se nenhuma entity selection contendo as entidades não elimináveis

Descrição

A função .drop() elimina as entidades pertencentes a seleção de entidades da tabela relacionada com sua dataclass no datastore. A entity selection permanece na memoria.

A eliminação de entidades é permanente e não pode ser desfeita. É recomendado chamar esta ação em uma transação para ter uma opção de recuperação.

Se encontrar uma entidade bloqueada durante a execução de .drop(), não é eliminado. Como padrão o método processa todas as entidades da seleção de entidades e retorna as entidades não elimináveis na entity selection. Se quiser que o método pare a execução na primeira entidade não eliminável encontrada, passe a constante dk stop dropping on first error no parâmetro mode.

Exemplo

Exemplo sem a opção dk stop dropping on first error:

 var $employees; $notDropped : cs.EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop() // $notDropped for uma entity selection que contém todas as entidades não suprimidas
 If($notDropped.length=0) //A ação de eliminação for exitosa, todas as entidades foram eliminadas
    ALERT("You have dropped "+String($employees.length)+" employees") //A seleção de entidades eliminada permanece na memoria
 Else
    ALERT("Problem during drop, try later")
 End if

Exemplo com a opção dk stop dropping on first error:

 var $employees; $notDropped : cs.EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop(dk stop dropping on first error) //$notDropped é uma entity selection que contém a primeira entidade não eliminada
 If($notDropped.length=0) //A ação de eliminação é exitosa, todas as entidades foram eliminadas
    ALERT("You have dropped "+String($employees.length)+" employees") //A seleção de entidades eliminada permanece na memória
 Else
    ALERT("Problem during drop, try later")
 End if

.extract()

Histórico

Versão	Mudanças
v18 R3	Adicionado

.extract( attributePath : Text { ; option : Integer } ) : Collection
.extract( attributePath { ; targetPath } { ; ...attributePathN : Text ; targetPathN : Text } ) : Collection

Parámetros	Tipo		Descrição
attributePath	Texto	->	Rota de atributo cujos valores serão extraídos para nova coleção
targetpath	Texto	->	Rota ou nome do atributo objetivo
option	Integer	->	ck keep null: inclui os atributos null na coleção devolvida (ignorados por padrão)
Resultado	Coleção	<-	Collection contendo valores extraídos

Descrição

A função .extract() retorna una coleção que contenha os valores de attributePath extraídos da entity selection.

attributePath pode ser:

• um atributo escalar de dataclass,
• entidade relacionada,
• entidades relacionadas.

Se attributePath não for válido, se devolve uma coleção vazia.

Esta função aceita duas sintaxes.

.extract( attributePath : Text { ; option : Integer } ) : Collection

Com esta sintaxe, .extract() preenche a coleção devolvida com os valores attributePath da entity selection.

Como padrão, as entidades para as que attributePath fornull ou indefinida são ignoradas na coleção resultante. Pode passar a constante ck keep null no parâmetro option para incluir esses valores como elementosnull na coleção retornada.

• Dataclass attributes with .kind = "relatedEntity" are extracted as a collection of entities (duplications are kept).
• Dataclass attributes with .kind = "relatedEntities" are extracted as a collection of entity selections.

.extract ( attributePath ; targetPath { ; ...attributePathN ; ... targetPathN}) : Collection

Com esta sintaxe, .extract() preenche a coleção devolvida com as propriedades attributePath da entity selection. Cada elemento da coleção devolvida é um objeto com as propriedades targetPath preenchidas com as propriedades attributePath correspondentes. Se mantém os valores null (o parámetro option se ignora) com esta sintaxe.

Se vários attributePath, forem dados, deve dar um targetPath para cada um. Só se extraem os pares válidos [attributePath, targetPath].

• Os atributos dataclass com .kind = "relatedEntity" se extraem como uma entidade.
• Os atributos dataclass com .kind = "relatedEntities" se extraem como uma entity selection

Os valores Null são avaliados como inferiores aos outros valores.

Exemplo

Dada a seguinte tabela e relação:

 var $firstnames; $addresses; $mailing; $teachers : Collection
  //
  //
  //$firstnames é uma coleção de Strings


 $firstnames:=ds. Teachers.all().extract("firstname")
  //
  //$addresses é uma coleção de entities relacionadas ao dataclass Address
  //Valores Null para o endereço são extraídos
 $addresses:=ds. Teachers.all().extract("address";ck keep null)
  //
  //
  //$mailing é uma coleção de objetos com propriedades "who" e "to"
  //conteúdo propriedade "who" é do tipo String
  //conteudo propriedade "to" é do tipo entity (Address dataclass)
 $mailing:=ds. Teachers.all().extract("lastname";"who";"address";"to")
  //
  //
  //$mailing é uma coleção de objetos com propriedades "who" e "city"
  //conteúdo propriedade "who" é tipo String
  //conteúdo propriedade "city" é tipo String
 $mailing:=ds. Teachers.all().extract("lastname";"who";"address.city";"city")
  //
  //$teachers é uma coleção de objetos com propriedades "where" e "who"
  //conteúdo propriedade "where" é String
  //conteúdo propriedade "who" é uma entity selection (Teachers dataclass)
 $teachers:=ds. Address.all().extract("city";"where";"teachers";"who")
  //
  //$teachers é uma coleção de entity selections
 $teachers:=ds. Address.all().extract("teachers")

.first()

Histórico

Versão	Mudanças
v17	Adicionado

.first() : 4D. Entity

Parameter	Type		Descrição
Resultado	4D. Entity	<-	Referencia à primeira entidade da entity selection (Null se a seleção estiver vazia)

Descrição

A função .first()retorna uma referência à entidade na primeira posição da entity selection.

O resultado desta função é similar a:

 $entity:=$entitySel[0]

Há, entretanto, uma diferença entre ambas as afirmações quando a seleção estiver vazia:

 var $entitySel : cs. EmpSelection
 var $entity : cs. EmpEntity
 $entitySel:=ds. Emp.query("lastName = :1";"Nonexistentname") //nenhuma entity correspondente
  //entity selection é esvaziada
 $entity:=$entitySel.first() //retorna Null
 $entity:=$entitySel[0]  //gera um erro

Exemplo

 var $entitySelection : cs. EmpSelection
 var $entity : cs. EmpEntity
 $entitySelection:=ds. Emp.query("salary > :1";100000)
 If($entitySelection.length#0)
    $entity:=$entitySelection.first()
 End if

.getDataClass()

Histórico

Versão	Mudanças
v17 R5	Adicionado

.getDataClass() : 4D. DataClass

Parámetros	Tipo		Descrição
Resultado	4D. DataClass	<-	DataClass a qual pertence a entity selection

Descrição

A função .getDataClass() retorna a dataclass da entity selection.

Esta função é principalmente útil no contexto do código genérico.

Exemplo

O seguinte código genérico duplica todas as entidades da entity selection:

  //duplicate_entities method
  //duplicate_entities($entity_selection)

 #DECLARE ( $entitySelection : 4D. EntitySelection )  
 var $dataClass : 4D. DataClass
 var $entity; $duplicate : 4D. Entity
 var $status : Object
 $dataClass:=$entitySelection.getDataClass()
 For each($entity;$entitySelection)
    $duplicate:=$dataClass.new()
    $duplicate.fromObject($entity.toObject())
    $duplicate[$dataClass.getInfo().primaryKey]:=Null //reset the primary key
    $status:=$duplicate.save()
 End for each

.isAlterable()

Histórico

Versão	Mudanças
v18 R5	Adicionado

.isAlterable() : Boolean

Parámetros	Tipo		Descrição
Resultado	Booleano	<-	True se a entity selection for modificável, do contrário False

Descrição

A função .isAlterable() devolve True se a entity selection for modificável, e False se não o for.

Para mais informação, consulte a seção Entity selections compartilháveis ou modificáveis.

Exemplo

Vai mostrar Form.products em uma list box para que o usuário possaa adicionar novos produtos. Se quiser ter certeza que é alterável para que o usuário possa adicionar novos produtos sem erro:

If (Not(Form.products.isAlterable()))
    Form.products:=Form.products.copy()
End if
...
Form.products.add(Form.product)

.isOrdered()

Histórico

Versão	Mudanças
v17	Adicionado

.isOrdered() : Boolean

Parámetros	Tipo		Descrição
Resultado	Booleano	<-	True se a entity selection for ordenada, do contrário False

Descrição

A função .isOrdered() devolve True se a entity selection for ordenada, e False se for desordenada.

Esta função não modifica a seleção de entidades original.

Para mais informação, consulte Entity selection ordenadas ou desordenadas.

Exemplo

 var $employees : cs.EmployeeSelection
 var $employee : cs.EmployeeEntity
 var $isOrdered : Boolean
 $employees:=ds.Employee.newSelection(dk keep ordered)
 $employee:=ds.Employee.get(714) // Obtém a entidade com chave primaria 714

  //Em uma entity selection ordenada, podemos adicionar a mesma entidade várias vezes (os duplicados se mantém)
 $employees.add($employee)
 $employees.add($employee)
 $employees.add($employee)

 $isOrdered:=$employees.isOrdered()
 If($isOrdered)
    ALERT("The entity selection is ordered and contains "+String($employees.length)+" employees")
 End if

.last()

Histórico

Versão	Mudanças
v17	Adicionado

.last() : 4D. Entity

Parámetros	Type		Descrição
Resultado	4D. Entity	<-	Referencia à última entidade da entity selection (Null se a entity selection estiver vazia)

Descrição

A função .last() devolve uma referência à entidad em última posição da entity selection.

O resultado desta função é similar a:

 $entity:=$entitySel[length-1]

Se a entity selection estiver vazia, a função devolve Null.

Exemplo

 var $entitySelection : cs. EmpSelection
 var $entity : cs. EmpEntity
 $entitySelection:=ds. Emp.query("salary < :1";50000)
 If($entitySelection.length#0)
    $entity:=$entitySelection.last()
 End if

.length

Histórico

Versão	Mudanças
v17	Adicionado

.length : Integer

Descrição

A função .count() devolve o número de entidades na entity selection com um valor não null em attributePath.

As entity selections sempre têm uma propriedade .length.

Exemplo

 var $vSize : Integer
 $vSize:=ds. Employee.query("gender = :1";"male").length
 ALERT(String(vSize)+" male employees found.")

.max()

Histórico

Versão	Mudanças
v17	Adicionado
v18 R6	Retorna indefinido se uma seleção de entidade for vazia

.max( attributePath : Text ) : any

Parámetros	Tipo		Descrição
attributePath	Texto	->	Rota do atributo que se utilizará para o cálculo
Resultado	any	<-	Valor mais alto do atributo

Descrição

A função .max() devolve o valor mais alto (ou máximo) entre todos os valores de attributePath na entity selection. Na verdade devolve o valor da última entidade da seleção de entidades tal como se ordenaría de forma ascendente utilizando a função .orderBy().

Se passar em attributePath uma rota a uma propriedade de objeto que contenha diferentes tipos de valores, a função .max() devolverá o valor máximo dentro do primeiro tipo escalar na ordem da lista de tipos 4D como padrão (ver a descrição de .sort()).

.max() returns undefined se a entity selection estiver vazia ou attributePath não for encontrado no atributo de objeto.

Um erro é retornado se:

• attributePath é um atributo relativo,
• attributePath designa um atributo que não existe na dataclass da entity selection.

Exemplo

Se quisermos encontrar o maior salário entre as funcionárias mulheres:

 var $sel : cs. EmpSelection
 var $maxSalary : Real
 $sel:=ds. Employee.query("gender = :1";"female")
 $maxSalary:=$sel.max("salary")

.min()

Histórico

Versão	Mudanças
v17	Adicionado
v18 R6	Retorna indefinido se uma seleção de entidade for vazia

.min( attributePath : Text ) : any

Parámetros	Tipo		Descrição
attributePath	Texto	->	Rota do atributo que se utilizará para o cálculo
Resultado	any	<-	Menor valor do atributo

Descrição

A função .min() devolve i valor mais baixo (ou mínimo) entre todos os valores de attributePath na entity selection. Retorna a primeira entidade da entity selection como seria ordenada em uma ordem ascendente se usasse a função .orderBy() (excluindo os valores null ).

Se passar em attributePath uma rota a uma propriedade objeto que contenha diferentes tipos de valores, a função .min() devolverá o valor mínimo dentro do primeiro tipo de valor escalar na ordem da lista de tipos (ver a descrição de .sort()).

.min() returns undefined if the entity selection is empty or attributePath is not found in the object attribute.

Um erro é retornado se:

• attributePath is a related attribute,
• attributePath designates an attribute that does not exist in the entity selection dataclass.

Exemplo

In this example, we want to find the lowest salary among all the female employees:

 var $sel : cs. EmpSelection
 var $minSalary : Real
 $sel:=ds. Employee.query("gender = :1";"female")
 $minSalary:=$sel.min("salary")

.minus()

Histórico

Versão	Mudanças
v17	Adicionado

.minus( entity : 4D.Entity ) : 4D.EntitySelection
.minus( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection

Parameter	Type		Descrição
entity	4D. Entity	->	Entity to substract
entitySelection	4D. EntitySelection	->	Entity selection to substract
Resultado	4D. EntitySelection	<-	New entity selection or a new reference on the existing entity selection

Descrição

The .minus() function excludes from the entity selection to which it is applied the entity or the entities of entitySelection and returns the resulting entity selection.

• If you pass entity as parameter, the function creates a new entity selection without entity (if entity belongs to the entity selection). If entity was not included in the original entity selection, a new reference to the entity selection is returned.
• If you pass entitySelection as parameter, the function returns an entity selection containing the entities belonging to the original entity selection without the entities belonging to entitySelection.

Pode comparar entity selections ordenadas ou desordenadas. A seleção resultante é sempre desordenada.

If the original entity selection or both the original entity selection and the entitySelection parameter are empty, an empty entity selection is returned.

If entitySelection is empty or if entity is Null, a new reference to the original entity selection is returned.

Se a entity selection inicial e o parâmetro não forem relacionados com a mesma dataclass, se produz um erro.

Exemplo 1

 EmployeeSelection
 $employees:=ds.Employee.query("firstName=:1";"S@")
 $notDropped:=$employees.drop() // $notDropped for uma entity selection que contém todas as entidades não suprimidas
 If($notDropped.length=0) //A ação de eliminação for exitosa, todas as entidades foram eliminadas
    ALERT("You have dropped "+String($employees.length)+" employees") //A seleção de entidades eliminada permanece na memoria
 Else
    ALERT("Problem during drop, try later")
 End if var $employees; $notDropped : cs.

Exemplo 2

We want to have a selection of female employees named "Jones" who live in New York :

 var $sel1; $sel2; $sel3 : cs. EmployeeSelection
 $sel1:=ds. Employee.query("name =:1";"Jones")
 $sel2:=ds. Employee.query("city=:1";"New York")
 $sel3:=$sel1.and($sel2).minus(ds. Employee.query("gender='male'"))

.or()

Histórico

Versão	Mudanças
v17	Adicionado

.or( entity : 4D.Entity ) : 4D.EntitySelection
.or( entitySelection : 4D.EntitySelection ) : 4D.EntitySelection

Parameter	Type		Descrição
entity	4D. Entity	->	Entidade a intersectar
entitySelection	4D. EntitySelection	->	Entity selection a intersectar
Resultado	4D. EntitySelection	<-	New entity selection or new reference to the original entity selection

Descrição

The .or() function combines the entity selection with the entity or entitySelection parameter using the logical (not exclusive) OR operator; it returns a new, unordered entity selection that contains all the entities from the entity selection and the parameter.

• If you pass entity as parameter, you compare this entity with the entity selection. If the entity belongs to the entity selection, a new reference to the entity selection is returned. Otherwise, a new entity selection containing the original entity selection and the entity is returned.
• If you pass entitySelection as parameter, you compare entity selections. A new entity selection containing the entities belonging to the original entity selection or entitySelection is returned (or is not exclusive, entities referenced in both selections are not duplicated in the resulting selection).

Pode comparar entity selections ordenadas ou desordenadas. A seleção resultante é sempre desordenada.

If the original entity selection and the entitySelection parameter are empty, an empty entity selection is returned. If the original entity selection is empty, a reference to entitySelection or an entity selection containing only entity is returned.

If entitySelection is empty or if entity is Null, a new reference to the original entity selection is returned.

Se a entity selection inicial e o parâmetro não forem relacionados com a mesma dataclass, se produz um erro.

Exemplo 1

 var $employees1; $employees2; $result : cs. EmployeeSelection
 $employees1:=ds. Employee.query("lastName = :1";"H@") //Returns "Colin Hetrick","Grady Harness"
 $employees2:=ds. Employee.query("firstName = :1";"C@") //Returns "Colin Hetrick", "Cath Kidston"
 $result:=$employees1.or($employees2) //$result contains "Colin Hetrick", "Grady Harness","Cath Kidston"

Exemplo 2

 var $employees; $result : cs. EmployeeSelection
 var $employee : cs. EmployeeEntity
 $employees:=ds. Employee.query("lastName = :1";"H@") // Devuelve "Colin Hetrick","Grady Harness", "Sherlock Holmes"
 $employee:=ds. Employee.get(686) //a entidade com chave primária 686 não pertence a entity selection $employees 
  //Coincide com a funcionária "Mary Smith"

 $result:=$employees.or($employee) //$result contém "Colin Hetrick", "Grady Harness", "Sherlock Holmes", "Mary Smith"

.orderBy()

Histórico

Versão	Mudanças
v17	Adicionado

.orderBy( pathString : Text ) : 4D.EntitySelection
.orderBy( pathObjects : Collection ) : 4D.EntitySelection

Paramètres	Tipo		Descrição
pathString	Texto	->	Rota(s) de atributos e instruções de clasificação para a entity selection
pathObjects	Coleção	->	Coleção de objetos criterio
Resultado	4D.EntitySelection	<-	Nova entity selection na ordem especificada

Descrição

A função .orderBy() devolve uma nova entity selection ordenada que contém todas as entidades da entity selection na ordem especificada pelos criterios pathString ou pathObjects.

• This method does not modify the original entity selection.

• For more information, please refer to the Ordered or unordered entity selection section.

You must use a criteria parameter to define how the entities must be sorted. Two different parameters are supported:

• pathString (Text) : This parameter contains a formula made of 1 to x attribute paths and (optionally) sort orders, separated by commas. The syntax is:

"attributePath1 {desc or asc}, attributePath2 {desc or asc},..."

The order in which the attributes are passed determines the sorting priority of the entities. By default, attributes are sorted in ascending order. You can set the sort order of a property in the criteria string, separated from the property path by a single space: pass "asc" to sort in ascending order or "desc" in descending order.

• pathObjects (collection): each element of the collection contains an object structured in the following way:

{
    "propertyPath": string,
    "descending": boolean
}

By default, attributes are sorted in ascending order ("descending" is false).

You can add as many objects in the criteria collection as necessary.

Null values are evaluated as less than other values.

Exemplo

// order by formula
 $sortedEntitySelection:=$entitySelection.orderBy("firstName asc, salary desc")
 $sortedEntitySelection:=$entitySelection.orderBy("firstName")

  // order by collection with or without sort orders
 $orderColl:=New collection
 $orderColl.push(New object("propertyPath";"firstName";"descending";False))
 $orderColl.push(New object("propertyPath";"salary";"descending";True))
 $sortedEntitySelection:=$entitySelection.orderBy($orderColl)

 $orderColl:=New collection
 $orderColl.push(New object("propertyPath";"manager.lastName"))
 $orderColl.push(New object("propertyPath";"salary"))
 $sortedEntitySelection:=$entitySelection.orderBy($orderColl)

.orderByFormula()

Histórico

Versão	Mudanças
v17 R6	Adicionado

.orderByFormula( formulaString : Text { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection
.orderByFormula( formulaObj : Object { ; sortOrder : Integer } { ; settings : Object} ) : 4D.EntitySelection

Parameter	Type		Descrição
formulaString	Texto	->	Formula string
formulaObj	Objeto	->	Formula object
sortOrder	Integer	->	dk ascending (default) or dk descending
settings	Objeto	->	Parameter(s) for the formula
Resultado	4D. EntitySelection	<-	New ordered entity selection

Descrição

The .orderByFormula() function returns a new, ordered entity selection containing all entities of the entity selection in the order defined through the formulaString or formulaObj and, optionally, sortOrder and settings parameters.

Esta função não modifica a entity selection original.

You can use either a formulaString or a formulaObj parameter:

• formulaString: you pass a 4D expression such as "Year of(this.birthDate)".
• formulaObj: pass a valid formula object created using the Formula or Formula from string command.

The formulaString or formulaObj is executed for each entity of the entity selection and its result is used to define the position of the entity in the returned entity selection. The result must be of a sortable type (boolean, date, number, text, time, null).

A null result is always the smallest value.

By default if you omit the sortOrder parameter, the resulting entity selection is sorted in ascending order. Optionnally, you can pass one of the following values in the sortOrder parameter:

Constante	Value	Comentário
dk ascending	0	Ascending sort order (default)
dk descending	1	Descending sort order

Within the formulaString or formulaObj, the processed entity and thus its attributes are available through the This command (for example, This.lastName).

You can pass parameter(s) to the formula using the args property (object) of the settings parameter: the formula receives the settings.args object in $1.

Exemplo 1

Sorting students using a formula provided as text:

 var $es1; $es2 : cs. StudentsSelection
 $es1:=ds. Students.query("nationality=:1";"French")
 $es2:=$es1.orderByFormula("length(this.lastname)") //ascending by default
 $es2:=$es1.orderByFormula("length(this.lastname)";dk descending)

Same sort order but using a formula object:

 var $es1; $es2 : cs. StudentsSelection
 var $formula : Object
 $es1:=ds. Students.query("nationality=:1";"French")
 $formula:=Formula(Length(This.lastname))
 $es2:=$es1.orderByFormula($formula) // ascending by default
 $es2:=$es1.orderByFormula($formula;dk descending)

Exemplo 2

A formula is given as a formula object with parameters; settings.args object is received as $1 in the computeAverage method.

In this example, the "marks" object field in the Students dataClass contains students' grades for each subject. A single formula object is used to compute a student's average grade with different coefficients for schoolA and schoolB.

 var $es1; $es2 : cs. StudentsSelection
 var $formula; $schoolA; $schoolB : Object
 $es1:=ds. Students.query("nationality=:1";"French")
 $formula:=Formula(computeAverage($1))

 $schoolA:=New object() //settings object
 $schoolA.args:=New object("english";1;"math";1;"history";1) // Coefficients to compute an average

  //Order students according to school A criteria
 $es2:=$es1.entitySelection.orderByFormula($formula;$schoolA)

 $schoolB:=New object() //settings object
 $schoolB.args:=New object("english";1;"math";2;"history";3) // Coefficients to compute an average

  //Order students according to school B criteria
 $es2:=$es1.entitySelection.orderByFormula($formula;dk descending;$schoolB)

  //
  // computeAverage method
  // -----------------------------
 #DECLARE ($coefList : Object) -> $result : Integer
 var $subject : Text
 var $average; $sum : Integer

 $average:=0
 $sum:=0

 For each($subject;$coefList)
    $sum:=$sum+$coefList[$subject]
 End for each

 For each($subject;This.marks)
    $average:=$average+(This.marks[$subject]*$coefList[$subject])
 End for each

 $result:=$average/$sum

.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

Parameter	Type		Descrição
queryString	Texto	->	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
Resultado	4D. EntitySelection	<-	New entity selection made up of entities from entity selection meeting the search criteria specified in queryString or formula

Descrição

The .query() function searches for entities that meet the search criteria specified in queryString or formula and (optionally) value(s) among all the entities in the entity selection, and returns a new object of type EntitySelection containing all the entities that are found. Se aplica carregamento diferido/lazy loading.

Esta função não modifica a entity selection original.

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

For detailed information on how to build a query using queryString, value, and querySettings parameters, please refer to the DataClass .query() function description.

By default if you omit the order by statement in the queryString, the returned entity selection is not ordered. Note however that, in Client/Server mode, it behaves like an ordered entity selection (entities are added at the end of the selection).

Exemplo 1

 var $entitySelectionTemp : cs. EmployeeSelection
 $entitySelectionTemp:=ds. Employee.query("lastName = :1";"M@")
 Form.emps:=$entitySelectionTemp.query("manager.lastName = :1";"S@")

Exemplo 2

More examples of queries can be found in the DataClass .query() page.

Veja também

.query() for dataclass

.queryPath

Histórico

Versão	Mudanças
v17	Adicionado

.queryPath : Text

Descrição

The .queryPath property contains a detailed description of the query as it was actually performed by 4D. This property is available for EntitySelection objects generated through queries if the "queryPath":true property was passed in the querySettings parameter of the .query() function.

For more information, refer to the querySettings parameter paragraph in the Dataclass.query() page.

.queryPlan

Histórico

Versão	Mudanças
v17	Adicionado

.queryPlan : Text

Descrição

The .queryPlan property contains a detailed description of the query just before it is executed (i.e., the planned query). This property is available for EntitySelection objects generated through queries if the "queryPlan":true property was passed in the querySettings parameter of the .query() function.

For more information, refer to the querySettings parameter paragraph in the Dataclass.query() page.

.refresh()

Histórico

Versão	Mudanças
v18 R3	Adicionado

.refresh()

| Parameter | Type | | Descrição | | --------- | ---- |::| ------------------------------- | | | | | Does not require any parameters |

Descrição

This function only works with a remote datastore (client / server or Open datastore connection).

The .refresh() function immediately "invalidates" the entity selection data in the local ORDA cache so that the next time 4D requires the entity selection, it will be reloaded from the database.

By default, the local ORDA cache is invalidated after 30 seconds. In the context of client / server applications using both ORDA and the classic language, this method allows you to make sure a remote application will always work with the latest data.

Exemplo 1

In this example, classic and ORDA code modify the same data simultaneously:

 //On a 4D remote

 var $selection : cs. StudentsSelection
 var $student : cs. StudentsEntity

 $selection:=ds. Students.query("lastname=:1";"Collins")
  //The first entity is loaded in the ORDA cache
 $student:=$selection.first()

  //Update with classic 4D, ORDA cache is not aware of if
 QUERY([Students];[Students]lastname="Collins")
 [Students]lastname:="Colin"
 SAVE RECORD([Students])

  //to get the latest version, the ORDA cache must be invalidated
 $selection.refresh()
  // Even if cache is not expired, the first entity is reloaded from disk
 $student:=$selection.first()

  //$student.lastname contains "Colin"

Exemplo 2

A list box displays the Form.students entity selection and several clients work on it.

// Form method:
 Case of
    :(Form event code=On Load)
       Form.students:=ds. Students.all()
 End case
  //
  //
  // On client #1, the user loads, updates, and saves the first entity
  // On client #2, the user loads, updates, and saves the same entity
  //
  //
  // On client #1:
 Form.students.refresh() // Invalidates the ORDA cache for the Form.students entity selection
  // The list box content is refreshed from the database with update made by client #2

.slice()

Histórico

Versão	Mudanças
v17	Adicionado

.slice( startFrom : Integer { ; end : Integer } ) : 4D.EntitySelection

Parameter	Type		Descrição
startFrom	Integer	->	Index to start the operation at (included)
end	Integer	->	Final do índice (não incluído)
Resultado	4D. EntitySelection	<-	New entity selection containing sliced entities (shallow copy)

Descrição

The .slice() function returns a portion of an entity selection into a new entity selection, selected from the startFrom index to the end index (end is not included) or to the last entity of the entity selection. This method returns a shallow copy of the entity selection (it uses the same entity references).

Esta função não modifica a entity selection original.

The returned entity selection contains the entities specified by startFrom and all subsequent entities up to, but not including, the entity specified by end. If only the startFrom parameter is specified, the returned entity selection contains all entities from startFrom to the last entity of the original entity selection.

• If startFrom < 0, it is recalculated as startFrom:=startFrom+length (it is considered as the offset from the end of the entity selection). If the calculated value < 0, startFrom is set to 0.
• If startFrom >= length, the function returns an empty entity selection.
• If end < 0, it is recalculated as end:=end+length.
• If end < startFrom (passed or calculated values), the method does nothing.

If the entity selection contains entities that were dropped in the meantime, they are also returned.

Exemplo 1

You want to get a selection of the first 9 entities of the entity selection:

var $sel; $sliced : cs. EmployeeSelection
$sel:=ds. Employee.query("salary > :1";50000)
$sliced:=$sel.slice(0;9) //

Exemplo 2

Assuming we have ds.Employee.all().length = 10

var $slice : cs. EmployeeSelection
$slice:=ds. Employee.all().slice(-1;-2) //tries to return entities from index 9 to 8, but since 9 > 8, returns an empty entity selection

.sum( )

Histórico

Versão	Mudanças
v17	Adicionado

.sum( attributePath : Text ) : Real

Parameter	Type		Descrição
attributePath	Texto	->	Rota do atributo que se utilizará para o cálculo
Resultado	Real	<-	Sum of entity selection values

Descrição

The .sum() function returns the sum for all attributePath values in the entity selection.

.sum() returns 0 if the entity selection is empty.

The sum can only be done on values of number type. If the attributePath is an object property, only numerical values are taken into account for the calculation (other value types are ignored). In this case, if attributePath leads to a property that does not exist in the object or does not contain any numeric values, .sum() returns 0.

Um erro é retornado se:

• attributePath is not a numerical or an object attribute,
• attributePath is a related attribute,
• attributePath is not found in the entity selection dataclass.

Exemplo

var $sel : cs. EmployeeSelection
var $sum : Real

$sel:=ds. Employee.query("salary < :1";20000)
$sum:=$sel.sum("salary")

.toCollection( )

Histórico

Versão	Mudanças
v17	Adicionado

.toCollection( { options : Integer { ; begin : Integer { ; howMany : Integer } } ) : Collection
.toCollection( filterString : Text {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection
.toCollection( filterCol : Collection {; options : Integer { ; begin : Integer { ; howMany : Integer }}} ) : Collection

Parameter	Type		Descrição
filterString	Texto	->	String with entity attribute path(s) to extract
filterCol	Coleção	->	Collection of entity attribute path(s) to extract
options	Integer	->	dk with primary key: adds the primary key dk with stamp: adds the stamp
begin	Integer	->	Designates the starting index
howMany	Integer	->	Number of entities to extract
Resultado	Coleção	<-	Collection of objects containing attributes and values of entity selection

Descrição

The .toCollection() function creates and returns a collection where each element is an object containing a set of properties and values corresponding to the attribute names and values for the entity selection.

If no filter parameter is passed or the first parameter contains an empty string or "*", all the attributes are extracted. Attributes with kind property as "relatedEntity" are extracted with the simple form: an object with property __KEY (primary key). Attributes with kind property as "relatedEntities" are not extracted.

Or, you can designate the entity attributes to extract using a filter parameter. You can use one of these two filters:

• filterString --a string with property paths separated with commas: "propertyPath1, propertyPath2, ...".
• filterCol --a collection of strings containing property paths: ["propertyPath1","propertyPath2",...]

If a filter is specified for an attribute of the relatedEntity kind:

• propertyPath = "relatedEntity" -> it is extracted with simple form
• propertyPath = "relatedEntity.*" -> all the properties are extracted
• propertyPath = "relatedEntity.propertyName1, relatedEntity.propertyName2, ..." -> only those properties are extracted

If a filter is specified for an attribute of the relatedEntities kind:

• propertyPath = "relatedEntities.*" -> all the properties are extracted
• propertyPath = "relatedEntities.propertyName1, relatedEntities.propertyName2, ..." -> only those properties are extracted

In the options parameter, you can pass the dk with primary key and/or dk with stamp selector(s) to add the entity's primary keys and/or stamps in extracted objects.

The begin parameter allows you to indicate the starting index of the entities to extract. You can pass any value between 0 and entity selection length-1.

The howMany parameter lets you specify the number of entities to extract, starting with the one specified in begin. Dropped entities are not returned but are taken into account according to howMany. For example, if howMany= 3 and there is 1 dropped entity, only 2 entities are extracted.

If howMany > length of the entity selection, the method returns (length - begin) objects.

An empty collection is returned if:

• the entity selection is empty, or
• begin is greater than the length of the entity selection.

Exemplo 1

The following structure will be used throughout all examples of this section:

Example without filter or options parameter:

 var $employeesCollection : Collection
 var $employees : cs. EmployeeSelection

 $employeesCollection:=New collection
 $employees:=ds. Employee.all()
 $employeesCollection:=$employees.toCollection()

Retorna:

[
    {
        "ID": 416,
        "firstName": "Gregg",
        "lastName": "Wahl",
        "salary": 79100,
        "birthDate": "1963-02-01T00:00:00.000Z",
        "woman": false,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    },
    {
        "ID": 417,
        "firstName": "Irma",
        "lastName": "Durham",
        "salary": 47000,
        "birthDate": "1992-06-16T00:00:00.000Z",
        "woman": true,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    }
]

Exemplo 2

Example with options:

var $employeesCollection : Collection
var $employees : cs. EmployeeSelection

$employeesCollection:=New collection
$employees:=ds. Employee.all()
$employeesCollection:=$employees.toCollection("";dk with primary key+dk with stamp)

Retorna:

[
    {
        "__KEY": 416,
        "__STAMP": 1,
        "ID": 416,
        "firstName": "Gregg",
        "lastName": "Wahl",
        "salary": 79100,
        "birthDate": "1963-02-01T00:00:00.000Z",
        "woman": false,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    },
    {
        "__KEY": 417,
        "__STAMP": 1,
        "ID": 417,
        "firstName": "Irma",
        "lastName": "Durham",
        "salary": 47000,
        "birthDate": "1992-06-16T00:00:00.000Z",
        "woman": true,
        "managerID": 412,
        "employerID": 20,
        "photo": "[object Picture]",
        "extra": null,
        "employer": {
            "__KEY": 20
        },
        "manager": {
            "__KEY": 412
        }
    }]

Exemplo 3

Example with slicing and filtering on properties:

var $employeesCollection; $filter : Collection
var $employees : cs. EmployeeSelection

$employeesCollection:=New collection
$filter:=New collection
$filter.push("firstName")
$filter.push("lastName")

$employees:=ds. Employee.all()
$employeesCollection:=$employees.toCollection($filter;0;0;2)

Retorna:

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl"
    },
    {
        "firstName": "Irma",
        "lastName": "Durham"
    }
]

Exemplo 4

Example with relatedEntity type with simple form:

var $employeesCollection : Collection
$employeesCollection:=New collection
$employeesCollection:=$employees.toCollection("firstName,lastName,employer")

retorna:

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "employer": {
            "__KEY": 20
        }
    },
    {
        "firstName": "Irma",
        "lastName": "Durham",
        "employer": {
            "__KEY": 20
        }
    },
    {
        "firstName": "Lorena",
        "lastName": "Boothe",
        "employer": {
            "__KEY": 20
        }
    }
   ]

Exemplo 5

Example with filterCol parameter:

var $employeesCollection; $coll : Collection
$employeesCollection:=New collection
$coll:=New collection("firstName";"lastName")
$employeesCollection:=$employees.toCollection($coll)

Retorna:

[
    {
        "firstName": "Joanna",
        "lastName": "Cabrera"
    },
    {
        "firstName": "Alexandra",
        "lastName": "Coleman"
    }
]

Exemplo 6

Example with extraction of all properties of a relatedEntity:

var $employeesCollection; $coll : Collection
$employeesCollection:=New collection
$coll:=New collection
$coll.push("firstName")
$coll.push("lastName")
$coll.push("employer.*")
$employeesCollection:=$employees.toCollection($coll)

Retorna:

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "employer": {
            "ID": 20,
            "name": "Irma",
        "lastName": "Durham",
        "employer": {
            "ID": 20,
            "name": "Lorena",
        "lastName": "Boothe",
        "employer": {
            "ID": 20,
            "name": "India Astral Secretary",
            "creationDate": "1984-08-25T00:00:00.000Z",
            "revenues": 12000000,
            "extra": null
        }
    }
  ]

Exemplo 7

Example with extraction of some properties of a relatedEntity:

var $employeesCollection : Collection
$employeesCollection:=New collection
$employeesCollection:=$employees.toCollection("firstName, lastName, employer.name")

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",

        "employer": {
            "name": "Irma",
        "lastName": "Durham",
        "employer": {
            "name": "Lorena",
        "lastName": "Boothe",
        "employer": {
            "name": "India Astral Secretary"
        }
    }]

Exemplo 8

Example with extraction of some properties of relatedEntities:

 var $employeesCollection : Collection
 $employeesCollection:=New collection
 $employeesCollection:=$employees.toCollection("firstName, lastName, directReports.firstName")

Retorna:

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "directReports": []
    },
    {
        "firstName": "Mike",
        "lastName": "Phan",
        "directReports": [
            {
                "firstName": "Gary"
            },
            {
                "firstName": "Sadie"
            },
            {
                "firstName": "Christie"
            }
        ]
    },
    {
        "firstName": "Gary",

        "lastName": "Reichert",
        "directReports": [
            {
                "firstName": "Rex"
            },
            {
                "firstName": "Jenny"
            },
            {
                "firstName": "Lowell"
            }
        ]
    }]

Exemplo 9

Example with extraction of all properties of relatedEntities:

var $employeesCollection : Collection
$employeesCollection:=New collection
$employeesCollection:=$employees.toCollection("firstName, lastName, directReports.*")

[
    {
        "firstName": "Gregg",
        "lastName": "Wahl",
        "directReports": []
    },    
    {
        "firstName": "Mike",
        "lastName": "Phan",
        "directReports": [
            {
                "ID": 425,
                "firstName": "Gary",
                "lastName": "Reichert",
                "salary": 65800,
                "birthDate": "1957-12-23T00:00:00.000Z",
                "woman": false,
                "managerID": 424,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 424
                }
            },
            {
                "ID": 426,
                "firstName": "Sadie",
                "lastName": "Gallant",
                "salary": 35200,
                "birthDate": "2022-01-03T00:00:00.000Z",
                "woman": true,
                "managerID": 424,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 424
                }
            }
                   ]
    },
    {
        "firstName": "Gary",
        "lastName": "Reichert",
        "directReports": [
            {
                "ID": 428,
                "firstName": "Rex",
                "lastName": "Chance",
                "salary": 71600,
                "birthDate": "1968-08-09T00:00:00.000Z",
                "woman": false,

                "managerID": 425,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 425
                }
            },
            {
                "ID": 429,
                "firstName": "Jenny",
                "lastName": "Parks",
                "salary": 51300,
                "birthDate": "1984-05-25T00:00:00.000Z",
                "woman": true,
                "managerID": 425,
                "employerID": 21,
                "photo": "[object Picture]",
                "extra": null,
                "employer": {
                    "__KEY": 21
                },
                "manager": {
                    "__KEY": 425
                }
            }
           ]
 }
]