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
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
[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.
- booleans
- strings
- números
- 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
orFormula 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 keydk 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
}
}
]
}
]