Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Esta página descreve as opções para armazenar grandes lotes de dados FHIR na
API Cloud Healthcare.
Importar recursos de FHIR
Use o método
fhirStores.import
para carregar recursos FHIR do Cloud Storage para a API Cloud Healthcare.
O método tem melhor desempenho ao carregar dados em um armazenamento FHIR vazio sem interferência
de outros aplicativos.
Ao decidir se deve usar o método fhirStores.import, considere as propriedades a seguir. Se fhirStores.import não for adequado para seu aplicativo, use o método fhir.executeBundle para carregar dados. Para informações sobre como chamar fhir.executeBundle, consulte
Como gerenciar recursos FHIR usando pacotes FHIR.
O método fhirStores.import aceita pacotes maiores que o
limite de 50 MB em fhir.executeBundle.
No entanto, o tamanho de cada recurso individual no pacote é
limitado a 10 MB.
O uso de fhirStores.import elimina as complexidades da execução de
grandes pacotes FHIR, como estes:
Como dividir pacotes FHIR em pacotes menores
Gerenciar vários horários de pacotes
Gerenciar erros temporários que podem ser tentados novamente no nível do recurso ou do pacote
Muitas vezes, essas vantagens superam as vantagens do uso de pacotes.
Cada recurso na entrada precisa ter um ID fornecido pelo cliente. Cada recurso é armazenado usando o ID fornecido, independentemente da configuração enableUpdateCreate no armazenamento FHIR.
O processo de importação não impõe integridade referencial, independentemente da configuração disableReferentialIntegrity no armazenamento FHIR. Não aplicar a integridade referencial permite importar recursos com interdependências arbitrárias sem considerar o agrupamento ou a ordem. Se os dados de entrada tiverem referências inválidas ou se alguns recursos não forem importados, o estado do armazenamento FHIR poderá violar a integridade referencial.
Se um recurso com um determinado ID já existir no armazenamento, a versão mais recente do recurso será substituída sem criar uma nova versão histórica. A substituição ocorre independentemente da configuração disableResourceVersioning no armazenamento FHIR. Se ocorrerem falhas temporárias durante a importação, um recurso importado poderá ser substituído mais de uma vez.
A operação de importação é idempotente, a menos que os dados de entrada tenham vários recursos válidos com o mesmo ID, mas conteúdos diferentes. Nesse caso, depois de concluir a importação, o armazenamento passa a ter exatamente um recurso com cada ID, mas as entradas duplicadas podem ter qualquer versão do conteúdo. Por exemplo, importar um milhão de recursos com o mesmo ID grava apenas um recurso no armazenamento.
Os contadores de resultados da operação não contam IDs duplicados como um erro. Cada recurso na entrada conta como um sucesso. Isso pode resultar em uma contagem de sucesso maior do que o número de recursos no armazenamento FHIR. Isso
geralmente ocorre ao importar dados organizados em pacotes produzidos por
Patient-everything, em que cada pacote tem a própria cópia de um recurso,
como Practitioner, que pode ser referenciado por muitos recursos do paciente.
Se alguns recursos não forem importados, como por causa de erros de análise, os recursos importados não serão revertidos. Por exemplo, se 5 dos 100
recursos não forem importados, os 95 recursos restantes serão importados para o
armazenamento FHIR.
Ao usar o formato BUNDLE, o método de importação rejeita pacotes com Bundle.type de history. O método de importação não aplica a semântica de processamento de pacotes para pacotes em lote ou de transações.
Ao contrário de fhir.executeBundle, os pacotes de transações não são executados como uma única transação, e as referências internas do pacote não são regravadas. O pacote é tratado como uma coleção de recursos a serem gravados conforme fornecido em Bundle.entry.resource, ignorando Bundle.entry.request. Por exemplo, isso permite a importação de pacotes de conjuntos de pesquisa gerados por uma pesquisa FHIR ou uma operação Patient-everything.
Usar pacotes FHIR
Consulte Pacotes FHIR para
conferir uma visão geral dos pacotes FHIR.
Quando usar pacotes FHIR
Considere as seguintes características e vantagens do uso do método fhir.executeBundle
ao decidir se ele será usado para armazenar recursos do FHIR:
Se for muito caro, em termos de custos de faturamento ou largura de banda de rede,
para criar um pipeline que armazene dados no Cloud Storage e os importe
usando fhirStores.import, use fhir.executeBundle.
Ao executar pacotes, a integridade da transação pode ser aplicada.
Ao executar pacotes, a validação do perfil FHIR pode ser aplicada.
Se você precisar enviar notificações do Pub/Sub
quando ocorrerem operações de criação, atualização ou exclusão do FHIR, use fhir.executeBundle.
As notificações do Pub/Sub não são enviadas quando os recursos FHIR são importados
usando fhirStores.import.
Se o tempo em que um recurso específico do FHIR precisa ser processado estiver em
segundos ou minutos, use fhir.executeBundle. Se o tempo em que um
recurso específico do FHIR precisa ser processado é em horas ou dias, use
fhirStores.import.
Se o projeto Google Cloud tiver muitas operações de longa duração (LROs)
realizando outras tarefas, talvez o desempenho seja melhor
com fhir.executeBundle do que com fhirStores.import.
Se o aplicativo que gerencia a operação fhirStores.import não tiver
uma boa estratégia para o seguinte, use fhir.executeBundle:
Como lidar com erros em massa
Como resolver falhas em um subconjunto de recursos FHIR ou em lotes inteiros
Quando não usar pacotes FHIR
Considere as seguintes limitações de fhir.executeBundle ao determinar
se ele será usado para armazenar recursos do FHIR:
Os pacotes têm a cota e o faturamento equivalentes aplicados às operações dentro
do pacote como se as operações fossem executadas fora dele. Por exemplo,
se um pacote tiver 10 operações POST, 5 operações GET e 1 operação DELETE,
a cota e o faturamento aplicados ao pacote serão os mesmos que se essas operações
tivessem sido executadas de forma independente.
Como resultado, o objetivo de reduzir os limites de cota e os custos de operação do FHIR não são motivos para usar
pacotes em vez de fhirStores.import.
Pacotes de transações grandes podem ter mais probabilidade de ter conflitos de transação,
o que leva à contenção de dados e operações com falha. Para informações sobre
como esses problemas podem ocorrer e como resolvê-los, consulte Prevenir erros do 429 Resource Exhausted operation_too_costly.
É possível alcançar e manter um alto throughput de dados usando pacotes em lote, o que
ajuda a evitar a contenção de dados. No entanto, os pacotes de lote não
têm recursos de consistência transacional, como integridade referencial.
Se um pacote for grande, mesmo que seja um pacote de lote, talvez a taxa de transferência de dados seja reduzida. Para mais informações, consulte Evite pacotes de transações grandes.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[[["\u003cp\u003eThis page outlines two primary methods for storing large amounts of FHIR data in the Cloud Healthcare API: using \u003ccode\u003efhirStores.import\u003c/code\u003e or \u003ccode\u003efhir.executeBundle\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efhirStores.import\u003c/code\u003e method is ideal for loading data from Cloud Storage into an empty FHIR store, accepting bundles larger than 50MB but with individual resource size limits of 10MB.\u003c/p\u003e\n"],["\u003cp\u003eUsing \u003ccode\u003efhirStores.import\u003c/code\u003e simplifies managing large FHIR data sets by removing the need to break down bundles, manage schedules, and handle transient errors, however, it does not enforce referential integrity or resource versioning.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efhir.executeBundle\u003c/code\u003e method is best when real-time processing of resources is necessary, such as when Pub/Sub notifications or FHIR profile validation is needed, and is preferable for applications with many long-running operations.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003efhir.executeBundle\u003c/code\u003e provides transactional integrity, but batch bundles lack transactional consistency, and large bundles may have data contention, impacting data throughput.\u003c/p\u003e\n"]]],[],null,["# FHIR import options\n\nThis page describes options for storing large batches of FHIR data in the\nCloud Healthcare API.\n| **Tip:** If you're importing data from an external bulk FHIR server, consider using the Google open source [Bulk FHIR Tools](https://github.com/google/bulk_fhir_tools) to load data directly into the Cloud Healthcare API.\n\nImport FHIR resources\n---------------------\n\nUse the\n[`fhirStores.import`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores/import)\nmethod to load FHIR resources from Cloud Storage into the Cloud Healthcare API.\nThe method performs best when loading data into an empty FHIR store without interference\nfrom other applications.\n\nTo call `fhirStores.import`, see\n[Importing and exporting FHIR resources using Cloud Storage](/healthcare-api/docs/how-tos/fhir-import-export).\n\nConsider the following properties of `fhirStores.import`\nmethod when deciding whether to use it. If `fhirStores.import` isn't suitable\nfor your application, consider using the\n[`fhir.executeBundle`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/executeBundle)\nmethod to load data. For information about how to call `fhir.executeBundle`, see\n[Managing FHIR resources using FHIR bundles](/healthcare-api/docs/how-tos/fhir-bundles).\n\n- The `fhirStores.import` method accepts bundles larger than the [50 MB limit](/healthcare-api/quotas#resource_limits) on `fhir.executeBundle`. However, the size of each individual resource within the bundle is limited to [10 MB](/healthcare-api/quotas#resource_limits).\n- Using `fhirStores.import` removes the complexities of executing\n large FHIR bundles, such as the following:\n\n - Breaking up FHIR bundles into smaller bundles\n - Managing multiple bundle schedules\n - Managing transient errors that can be retried at the resource or bundle level\n\n Often, these advantages outweigh the advantages from using bundles.\n- Each resource in the input must contain a client-supplied ID. Each resource is\n stored using the provided ID regardless of the\n [`enableUpdateCreate`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.enable_update_create)\n setting on the FHIR store.\n\n- The import process doesn't enforce referential integrity, regardless of the\n [`disableReferentialIntegrity`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.disable_referential_integrity)\n setting on the FHIR store. Not enforcing referential integrity lets you\n import resources with arbitrary interdependencies without considering grouping\n or ordering. If the input data contains invalid references or if some\n resources fail to import, the state of the FHIR store might violate\n referential integrity.\n\n- If a resource with a given ID already exists in the store, the most recent\n version of the resource is overwritten without creating a new historical\n version. The overwriting occurs regardless of the\n [`disableResourceVersioning`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.disable_resource_versioning)\n setting on the FHIR store. If transient failures occur during the import, a\n successfully imported resource could be overwritten more than once.\n\n- The import operation is idempotent unless the input data contains multiple\n valid resources with the same ID but different contents. In that case, after\n the import completes, the store contains exactly one resource with each ID,\n but the duplicate entries could contain any version of the contents. For\n example, importing a million resources with the same ID writes only one\n resource to the store.\n\n- The operation result counters don't count duplicate IDs as an error. Each\n resource in the input counts as one success. This could result\n in a success count larger than the number of resources in the FHIR store. This\n often occurs when importing data organized in bundles produced by\n `Patient-everything` where each bundle contains its own copy of a resource,\n such as `Practitioner`, that might be referenced by many Patient resources.\n\n- If some resources fail to import, such as due to parsing errors,\n successfully imported resources aren't rolled back. For example, if 5 of 100\n resources fail to import, the remaining 95 resources are imported into the\n FHIR store.\n\n- When using the `BUNDLE` format, the import method rejects bundles with\n `Bundle.type` of `history`. The import method doesn't apply the bundle\n processing semantics for batch or transaction bundles.\n Unlike in `fhir.executeBundle`, transaction bundles aren't executed as a\n single transaction and bundle-internal references aren't rewritten. The\n bundle is treated as a collection of resources to be written as provided in\n `Bundle.entry.resource`, ignoring `Bundle.entry.request`. For example, this\n allows the import of searchset bundles produced by a FHIR search or\n `Patient-everything` operation.\n\nUse FHIR bundles\n----------------\n\nSee [FHIR bundles](/healthcare-api/docs/how-tos/fhir-bundles#fhir_bundles) for\nan overview of FHIR bundles.\n\n### When to use FHIR bundles\n\nConsider the following characteristics and advantages of using the `fhir.executeBundle`\nmethod when deciding whether to use it to store FHIR resources:\n\n- If it is too costly, either in terms of billing costs or network bandwidth, to build a pipeline that stores data in Cloud Storage and then imports the data using `fhirStores.import`, use `fhir.executeBundle`.\n- When executing bundles, transaction integrity can be enforced.\n- When executing bundles, FHIR profile validation can be enforced.\n- If you need to send [Pub/Sub notifications](/healthcare-api/docs/how-tos/pubsub) when FHIR create, update, or delete operations occur, use `fhir.executeBundle`. Pub/Sub notifications are not sent when FHIR resources are imported using `fhirStores.import`.\n- If the time at which a particular FHIR resource must be processed is in in seconds or minutes, use `fhir.executeBundle`. If the time at which a particular FHIR resource must be processed is in hours or days, use `fhirStores.import`.\n- If your Google Cloud project has many existing long-running operations (LRO) performing other tasks, you might see better performance with `fhir.executeBundle` over `fhirStores.import`.\n- If the application managing the `fhirStores.import` operation doesn't\n have a good strategy for the following, use `fhir.executeBundle`:\n\n - Handling bulk errors\n - Addressing failures on a subset of FHIR resources or entire batches\n\n### When not to use FHIR bundles\n\nConsider the following limitations of `fhir.executeBundle` when determining\nwhether to use it to store FHIR resources:\n\n- Bundles have the equivalent quota and billing applied to the operations inside\n the bundle as if the operations were executed outside of the bundle. For example,\n if a bundle has 10 `POST` operations, 5 `GET` operations, and 1 `DELETE` operation,\n the quota and billing applied to the bundle is the same as if those operations\n were executed independently.\n\n As a result, aiming to lower quota limits and FHIR operation costs are not reasons to use\n bundles instead of `fhirStores.import`.\n- Large transaction bundles might be more likely to have transaction conflicts\n which leads to data contention and failed operations. For information on\n how these issues can occur, and how to resolve them, see [Prevent `429 Resource Exhausted operation_too_costly` errors](/healthcare-api/docs/best-practices-data-throughput#prevent-429).\n\n- You can achieve and maintain high data throughput using batch bundles, which\n helps you to avoid data contention. However, batch bundles do not\n have transactional consistency\n capabilities, such as [referential integrity](/healthcare-api/docs/concepts/fhir-referential-integrity)\n\n- If a bundle is large, even if it's a batch bundle, you might see reduced\n data throughput. For more information, see [Avoid large transaction bundles](/healthcare-api/docs/best-practices-data-throughput#avoid-large)."]]
