SwiftData: Saiba mais sobre herança e migração de esquema

Olá! Meu nome é Rishi Verma. Sou engineer na equipe SwiftData. Esta é a sessão “SwiftData: detalhes sobre herança e migração de esquema”. O SwiftData foi lançado no iOS 17 e permite modelar e gravar os dados do seu app em Swift em todas as plataformas da Apple. Ele permite escrever código rápido, eficiente e seguro usando os recursos modernos da linguagem Swift. E isso continua neste vídeo com uma introdução ao uso da herança de classes e ao entendimento de quando a herança é a escolha certa. Com a adoção da herança e a evolução do Schema, discutiremos as estratégias de migração usadas para preservar os dados. Depois, falaremos de algumas formas de personalizar buscas e consultas no SwiftData para obter o melhor desempenho. Por fim, veremos como observar mudanças nos modelos feitas local e remotamente. Já há algumas versões, temos usado um app familiar, o SampleTrips. É um app escrito em SwiftUI para acompanhar todas as diferentes viagens que planejei. Para usar o SwiftData com os modelos no app, preciso importar o framework e decorar cada modelo com a macro Model.

Na definição do app, adicionamos o modificador modelContainer no WindowGroup, que informa toda a hierarquia de visualizações sobre o modelo Trip. Com o modelContainer configurado, posso atualizar minha view para usar a macro Query. Vamos remover os dados estáticos e preencher a view usando a macro Query, que vai gerar o código para buscar as viagens do contêiner de modelo.

É isso. O app armazena as viagens que eu crio e se encaixa bem nas views da SwiftUI. O SwiftData oferece armazenamento, além de modelagem e migração do seu esquema, gerenciamento de grafos, sincronização com o CloudKit e muito mais. O recurso mais recente a chegar ao SwiftData é a herança de classes. O iOS 26 agora permite criar um grafo de modelos que aproveita a herança. A herança de classes é uma ferramenta poderosa. Vamos saber quando ela é a ferramenta certa para o trabalho. A herança funciona bem quando os modelos formam uma hierarquia natural e compartilham características. O modelo Trip tem destination, startDate e endDate, propriedades de que toda viagem precisa para sabermos para onde e quando vamos. Qualquer nova subclasse de Trip já terá essas propriedades e outros comportamentos compartilhados definidos em Trip. O modelo Trip também é um domínio amplo. Há muitos tipos de viagens que fazemos em nossas vidas. Uma subclasse de Trip deve ser um subdomínio natural que se encaixe no domínio mais amplo do Trip.

No app de exemplo Trips, muitas viagens se encaixam em dois subdomínios naturais: viagens pessoais e de negócios. Com esses dois novos modelos expressando subdomínios naturais de uma viagem, quero adicionar propriedades e comportamentos específicos dessas subclasses. Para as viagens pessoais, vou adicionar uma enumeração que captura o motivo para estar fazendo essa viagem específica. Para a viagem de negócios, quero adicionar uma propriedade para registrar meu per diem, assim saberei quanto gastar na próxima aventura de trabalho. Vamos fazer isso no app de exemplo Trips e criar uma experiência melhor. Aqui está a classe Trip com as propriedades que queremos compartilhar com as subclasses. Vamos adicionar duas subclasses ao app Trips, uma para viagens de negócios e outra para viagens pessoais. Preciso decorá-las com @available no iOS 26 ou posterior para que estejam alinhadas com a compatibilidade com a herança do SwiftData. Vamos adicionar as propriedades específicas dos subdomínios às subclasses. Posso adicionar um per diem à BusinessTrip e definir seu valor inicial. Para PersonalTrip, adicionamos uma enumeração Reason para registrar o motivo para fazer a viagem pessoal. A última coisa que precisamos fazer é atualizar o esquema para incluir as novas subclasses. Vamos adicionar BusinessTrip e PersonalTrip ao modificador modelContainer e podemos começar. O app de exemplo Trips está pronto para aproveitar as viagens pessoais em azul e as de negócios em verde, sem nenhum código especial adicional. A herança de classes é uma ferramenta poderosa, mas não serve para todo tipo de problema. Vamos discutir quando você deve utilizar a herança.

Há alguns cenários em que a herança é o caminho certo. Se os modelos expressam uma relação hierárquica e têm características comuns que você deseja estender, a herança pode ser a escolha correta, pois seus tipos formam uma relação “é-um”.

Ao usar modelos herdados, uma viagem pessoal É-UM tipo de viagem, então sempre que trabalho com um tipo Trip, como na consulta de viagens nesta visualização, posso esperar encontrar todos os tipos de viagens, incluindo pessoais e de negócios, além de instâncias da própria classe principal Trip. Temos as viagens representadas por aviões com a mesma cor da interface, voando do contêiner de modelo para o contexto de modelo que possibilita a consulta. Entretanto, a herança não deve ser usada apenas para compartilhar características comuns entre modelos. Ao criar subclasses para todos os modelos com uma propriedade name, a hierarquia de classes teria muitos subdomínios que compartilham uma única propriedade para um propósito comum, enquanto todas as outras características estariam isoladas em seus próprios subdomínios. Como esses subdomínios não formam uma hierarquia natural, eles são expressos por meio da conformidade a um protocolo. A conformidade com protocolos permite que domínios distintos compartilhem comportamentos, mas não outras características não relacionadas. Outro motivo para usar herança depende de como você consulta ou busca modelos.

Há várias formas de consultar dados, e estamos usando a macro Query para buscar todas as viagens do contêiner de modelo e direcionar as visualizações. Este é um exemplo de busca profunda.

Se sempre buscarmos todas as viagens utilizando somente o tipo Trip, deveremos considerar PersonalTrip ou BusinessTrip como uma propriedade de Trip, em vez de uma subclasse. Se as consultas ou buscas recuperam apenas os tipos das classes folha, isso é conhecido como busca rasa. Nesse cenário, considere simplificar os modelos, já que Trip nunca é consultado ou utilizado como tipo. Se você usa buscas profundas e rasas, a herança vai ajudar, pois você vai pesquisar todas as viagens ou um subtipo específico, como PersonalTrips, para direcionar uma view personalizada para esse tipo. Vamos ver como podemos atualizar o app Trips para mostrar apenas as viagens pessoais ou de negócios.

Vamos usar um controle segmentado para mostrar todas as viagens e as subclasses específicas.

O segmento selecionado pode ser usado para criar um predicado que determina se a classe é de um tipo específico pela a palavra-chave “is”. Por exemplo, estou verificando se é uma PersonalTrip. Fornecemos o predicado e classificamos pela startDate para inicializar a consulta. Vamos conferir no app. Ele começa na visualização de viagens para eu ver todas as viagens. Posso restringir as visualizações para as subclasses específicas. Excelente! É assim que aproveitamos a herança de classes no iOS 26. Mas ainda não terminei. Fizemos mudanças importantes no nosso esquema e devemos considerar o que isso significa para o app e como migrar nossos dados. O app SampleTrips passou por várias evoluções nas últimas versões. Vamos registrar essas mudanças nos esquemas versionados e em um plano de migração de esquema, para que o app preserve os dados do usuário ao ser atualizado para a versão mais recente do app de exemplo Trips.

Tudo começou com o primeiro vídeo, onde apresentamos o SwiftData no iOS 17 e usamos o Trips para guiar a adoção. Ao longo desses vídeos, aprendemos a tornar o nome de uma viagem único e como alterar o nome original de uma propriedade para preservar os dados durante a migração.

Para o iOS 17, construímos nosso esquema versionado com um novo identificador de versão 2.0 e mostramos o modelo Trip modificado, com um nome único e as datas de início e término renomeadas.

Adicionamos uma etapa de migração personalizada para remover duplicatas das Trips existentes. Aqui, usamos a função fetch do ModelContext para buscar todas as viagens, a fim de remover duplicatas.

No iOS 18, usamos os macros Index e Unique, além de marcar quais propriedades seriam preservadas durante a exclusão.

Isso permite identificar nossos modelos mesmo após a exclusão do repositório de dados.

No esquema versionado para o iOS 18, marcamos a versão como 3 e registramos as mudanças no modelo Trip. Fizemos novo uso das macros Unique e Index para garantir que nossos dados sejam desduplicados e eficientes nas buscas e consultas. Também decoramos essas propriedades com preserveValueOnDeletion, para identificar a viagem excluída ao consumir o histórico persistente.

Adicionamos outra etapa de migração personalizada para desduplicar as viagens ao migrar da versão 2 para a versão 3. No iOS 26, adicionaremos a versão 4 com subclasses e uma etapa de migração leve. Para o esquema da versão atual, marcamos como versão 4 e listamos os modelos do esquema, incluindo as novas subclasses. Como as subclasses foram decoradas com o iOS 26 ou posterior, o mesmo ocorre com o esquema de versão. Precisamos adicionar uma etapa de migração leve da versão 3 para a versão 4, com a mesma disponibilidade necessária antes. Com o esquema da versão final e a etapa de migração criados, podemos encapsular tudo isso em um plano de migração de esquema, para fornecer a ordem dos esquemas de versão e as etapas de migração a serem executadas. O plano de migração de esquema consiste em um conjunto de esquemas na ordem em que foram lançados. Quando o iOS 26 for lançado, vamos incluir o esquema mais recente com subclasses, seguido por uma sequência de etapas de migração para migrar de uma versão para a outra. É assim que criamos nosso plano de migração de esquema. Agora que criamos nosso esquema versionado e seu respectivo plano de migração, o próximo passo é utilizá-los ao criar o contêiner de modelo para o app de exemplo Trips. Vamos voltar ao modificador modelContainer e atualizá-lo para usar um contêiner de modelo com um plano de migração de esquema. Começamos adicionando uma nova propriedade container ao app, onde construiremos o esquema versionado com a versão 4 e forneceremos o plano de migração de esquema ao inicializador do ModelContainer. Vamos atualizar o modificador modelContainer para usar o novo contêiner migrável. Com tudo configurado, garantimos que as atualizações do app de exemplo Trips para utilizar herança possam migrar pelas diversas iterações lançadas anteriormente, preservando os dados do cliente.

Agora que lidamos com a migração, vamos considerar onde melhorar as consultas e buscas utilizadas para direcionar nossas views e etapas de migração. Atualizamos a consulta com o segmento escolhido usando um predicado. Em um vídeo anterior, tínhamos uma barra de busca. Vamos adicionar de novo esse recurso e focar o processamento do texto de busca inserido pelo cliente. Começamos construindo um predicado com o searchText fornecido. Primeiro, verificamos se o texto está vazio. Se não estiver vazio, criamos um predicado composto para verificar se o nome ou o destino da viagem contém o texto fornecido. Depois, vamos criar um predicado composto combinando o predicado de busca com o de classe. Por fim, atualizamos o inicializador de consulta para usar o novo predicado composto. Com essa atualização, posso tocar na barra de busca, digitar um texto para filtrar as viagens e até refinar com um controle segmentado. Filtrar e classificar são algumas das formas de personalizar consultas e buscas. Vamos ver outras maneiras de personalizar as buscas no SwiftData. Está é a etapa de migração personalizada da versão 1 para a versão 2. Usaremos o bloco willMigrate para buscar todas as Trips. Porém, na minha lógica de desduplicação, acesso apenas a propriedade name, pois ela é única na versão 2, e a utilizo para garantir que não existam duplicatas. Como name é a única propriedade acessada, posso atualizar o fetchDescriptor para usar propertiesToFetch com o name, garantindo que nossos modelos Trip carreguem apenas os dados necessários durante a migração. Além disso, já podemos acessar uma relação específica, neste caso, vou reatribuir uma acomodação se encontrar um duplicado, podemos fazer o mesmo aprimoramento usando relationshipsToPrefetch. Vamos adicionar aqui a relação livingAccommodation.

Agora que adotamos propriedades de prefetch, também podemos atualizar o código do widget no app de exemplo Trips para torná-lo mais eficiente. No widget do app de exemplo Trips, temos uma consulta para a viagem mais recente. No entanto, isso pode ser melhorado para buscar um único valor. Atualmente, o código do widget usa apenas o primeiro resultado da busca. Podemos tornar isso mais eficiente definindo um limite de busca.

Ao definir o limite de busca, o widget obtém a primeira viagem que corresponda ao predicado e não precisará se preocupar com cenários em que eu tenha muitas viagens planejadas para o futuro. Com as consultas e buscas aprimoradas, vamos explorar como detectar quando o modelo foi alterado. Todos os modelos persistentes são Observable, então podemos usar o withObservationTracking para reagir a alterações nas propriedades de interesse dos nossos modelos. Para observar alterações nas datas de início e fim da viagem, podemos adicionar a função datesChangedAlert para que, se o usuário modificar as datas, um alerta seja exibido.

Podemos observar alterações locais feitas em nossos PersistentModels dessa forma, e isso é muito útil para mudanças realizadas localmente. Para saber mais sobre as novidades em Observable, confira Novidades no Swift. Nem todas as alterações são Observable, apenas as feitas nos modelos dentro do mesmo processo, não as feitas no repositório de dados por outro processo, como um widget, extensão ou até mesmo outro contêiner de modelo no app. Alterações locais ou internas no app ocorrem quando você tem vários contextos de modelo usando o mesmo contêiner de modelo. Esses outros modelos de contato conseguem ver as alterações uns dos outros e, no caso de Query, essas mudanças são aplicadas automaticamente. Se você estiver usando as APIs de busca de contexto do modelo, as alterações feitas em outro contexto não serão vistas até que uma nova busca seja acionada.

Uma ação externa pode modificar seus dados, como um widget ou outro app gravando no contêiner compartilhado via App Group. Essas alterações atualizarão a view com suporte da consulta. As buscas feitas com fetch precisarão ser feitas de novo. Refazer a busca pode ser custoso, especialmente se nada relevante para o processamento do nosso modelo tiver mudado.

Felizmente, o SwiftData mantém um histórico armazenado. Posso saber quais modelos foram alterados, quando foram alterados, quem fez as mudanças e até quais propriedades foram atualizadas. Utilizamos o preservedValueOnDeletion em várias propriedades do Trip, assim, quando uma viagem é excluída, o histórico mantém um registro que pode ser analisado para identificar a viagem excluída. Para saber mais, confira “Monitorar alterações em modelos com o histórico do SwiftData”, da WWDC24.

Vamos usar o histórico armazenado para saber se precisamos refazer a busca. A primeira coisa a fazer é buscar o token de histórico mais recente do contêiner. Assim, podemos usar esse token como marcador para indicar até onde lemos o banco de dados. É parecido com um marcador de página mostrando onde paramos de ler em nosso livro favorito. Configuramos uma busca no histórico utilizando um descriptor para DefaultHistoryTransaction. Se houver muito histórico armazenado, podemos acabar buscando muitos dados só para obter o último token. Uma novidade do iOS 26 é a capacidade de buscar o histórico com sortBy. Podemos especificar qualquer propriedade da transação, como author ou transactionIdentifier, como chave para classificar o resultado do histórico. Vamos adotar o novo sortBy e configurá-lo para transactionIdentifier, mas em ordem reversa, para as transações mais recentes aparecem primeiro. Como só nos interessa a primeira transação, que é a mais recente, vamos limitar o resultado a 1. É assim que buscamos e armazenamos o token de histórico mais recente. Vamos salvar esse token para usar nas próximas buscas de histórico. Quando uma nova alteração ocorrer, por exemplo, o Widget atualizar uma viagem, uma nova entrada será adicionada ao histórico e o app poderá buscar o histórico para verificar se houve mudanças desde o último token. Agora que temos um token de histórico armazenado, podemos criar um predicado que busque apenas o histórico posterior a esse token. Para encontrar só as mudanças que nos interessam, montamos a lista de entidades que queremos saber se foram alteradas. Queremos saber se uma viagem ou a acomodações foi modificada, caso o widget tenha confirmado onde estamos hospedados. Vamos usar os nomes das entidades no predicado de mudanças para filtrar as alterações no histórico para os tipos desejados. Por fim, com o predicado do token e o predicado de mudanças, criamos nosso predicado composto. Com essas alterações aplicadas, ao buscar o histórico, retornamos apenas os registros posteriores ao nosso token e referentes às entidades que temos interesse em processar. Com uma busca de histórico mais eficiente, podemos evitar a repetição quando não há mudanças relevantes. O histórico do SwiftData facilita esse processo. Com isso, sabemos como observar mudanças locais e remotas em nossos modelos e dados. Espero que você este vídeo tenha sido útil e que você possa usar o SwiftData para suas necessidades de armazenamento. Ao criar seu grafo de modelos, avalie se a herança é a abordagem adequada e quais serão as implicações de migração conforme seu grafo evolui. Na hora de obter seus dados, crie fetchers e queries mais vançados e eficientes. Saber quando seus dados foram alterados pode ser inestimável. A observação e o histórico armazenado cuidam disso para você. Isso é tudo. Boa viagem!