Export with history and soft deletes

docs/rest/ExportRequests.http

@@ -71,6 +71,13 @@ Accept: application/fhir+json
 Prefer: respond-async
 Authorization: Bearer {{bearer.response.body.access_token}}
 
+### Export with history and soft deleted records
+# @name export
+GET https://{{hostname}}/$export?includeAssociatedData=_history,_deleted
+Accept: application/fhir+json
+Prefer: respond-async
+Authorization: Bearer {{bearer.response.body.access_token}}
+
 ### Get Export request
 GET {{exportLocation}}
 Authorization: Bearer {{bearer.response.body.access_token}}

src/Microsoft.Health.Fhir.Api/Features/Filters/ValidateExportRequestFilterAttribute.cs

@@ -45,6 +45,7 @@ public ValidateExportRequestFilterAttribute()
                 KnownQueryParameterNames.Format,
                 KnownQueryParameterNames.TypeFilter,
                 KnownQueryParameterNames.IsParallel,
+                KnownQueryParameterNames.IncludeAssociatedData,
                 KnownQueryParameterNames.MaxCount,
                 KnownQueryParameterNames.AnonymizationConfigurationCollectionReference,
                 KnownQueryParameterNames.AnonymizationConfigurationLocation,

src/Microsoft.Health.Fhir.Api/Resources.resx

@@ -408,4 +408,10 @@
     <value>Invalid combination of processing logic and bundle type: {0} and {1}.</value>
     <comment>Error message when there is a invalid/unknown combination of a bundle type and a processing logic.</comment>
   </data>
+  <data name="TypeFilterNotSupportedWithHistoryOrDeletedExport" xml:space="preserve">
+    <value>The request "_typeFilter" cannot be used with an export request with historical or soft deleted resources.</value>
+  </data>
+  <data name="InvalidExportAssociatedDataParameter" xml:space="preserve">
+    <value>The export parameter "includeAssociatedData" contains an invalid parameter.</value>
+  </data>
 </root>

src/Microsoft.Health.Fhir.Core.UnitTests/Features/Operations/Export/ExportJobTaskTests.cs

@@ -6,6 +6,7 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.Linq;
 using System.Linq.Expressions;
 using System.Net;
 using System.Threading;
@@ -20,6 +21,7 @@
 using Microsoft.Health.Extensions.DependencyInjection;
 using Microsoft.Health.Fhir.Core.Configs;
 using Microsoft.Health.Fhir.Core.Exceptions;
+using Microsoft.Health.Fhir.Core.Features;
 using Microsoft.Health.Fhir.Core.Features.Context;
 using Microsoft.Health.Fhir.Core.Features.Operations;
 using Microsoft.Health.Fhir.Core.Features.Operations.Export;
@@ -321,40 +323,71 @@ public async Task GivenThereAreMultiplePagesOfSearchResultsWithSinceParameter_Wh
             Assert.True(secondCapturedSearch);
         }
 
-        private Expression<Predicate<IReadOnlyList<Tuple<string, string>>>> CreateQueryParametersExpression(string resourceType)
+        [Fact]
+        public async Task GivenAnExportJobWithHistoryAndSoftDeletes_WhenExecuted_ThenAllResourcesAreExportedToTheProperLocation()
+        {
+            bool capturedSearch = false;
+
+            var exportJobRecordIncludeHistory = CreateExportJobRecord(
+                exportJobType: ExportJobType.Patient,
+                includeHistory: true,
+                includeDeleted: true,
+                maximumNumberOfResourcesPerQuery: 1);
+            SetupExportJobRecordAndOperationDataStore(exportJobRecordIncludeHistory);
+
+            _searchService.SearchAsync(
+                null,
+                Arg.Is(CreateQueryParametersExpression(KnownResourceTypes.Patient, includeHistory: true, includeDeleted: true)),
+                _cancellationToken,
+                true)
+                .Returns(x =>
+                {
+                    capturedSearch = true;
+
+                    return CreateSearchResult();
+                });
+
+            await _exportJobTask.ExecuteAsync(_exportJobRecord, _weakETag, _cancellationToken);
+
+            Assert.True(capturedSearch);
+        }
+
+        private Expression<Predicate<IReadOnlyList<Tuple<string, string>>>> CreateQueryParametersExpression(string resourceType, bool includeHistory = false, bool includeDeleted = false)
         {
             return arg => arg != null &&
-                Tuple.Create("_count", "1").Equals(arg[0]) &&
-                Tuple.Create("_lastUpdated", $"le{_exportJobRecord.Till}").Equals(arg[1]) &&
-                Tuple.Create("_type", resourceType).Equals(arg[2]);
+                arg.Any(x => x.Item1 == "_count" && x.Item2 == "1") &&
+                arg.Any(x => x.Item1 == "_lastUpdated" && x.Item2 == $"le{_exportJobRecord.Till}") &&
+                arg.Any(x => x.Item1 == "_type" && x.Item2 == resourceType) &&
+                arg.Any(x => x.Item1 == "_includeHistory" && x.Item2 == includeHistory.ToString()) &&
+                arg.Any(x => x.Item1 == "_includeDeleted" && x.Item2 == includeDeleted.ToString());
         }
 
         private Expression<Predicate<IReadOnlyList<Tuple<string, string>>>> CreateQueryParametersExpression(PartialDateTime since, string resourceType)
         {
             return arg => arg != null &&
-                Tuple.Create("_count", "1").Equals(arg[0]) &&
-                Tuple.Create("_lastUpdated", $"le{_exportJobRecord.Till}").Equals(arg[1]) &&
-                Tuple.Create("_lastUpdated", $"ge{since}").Equals(arg[2]) &&
-                Tuple.Create("_type", resourceType).Equals(arg[3]);
+                arg.Any(x => x.Item1 == "_count" && x.Item2 == "1") &&
+                arg.Any(x => x.Item1 == "_lastUpdated" && x.Item2 == $"le{_exportJobRecord.Till}") &&
+                arg.Any(x => x.Item1 == "_lastUpdated" && x.Item2 == $"ge{since}") &&
+                arg.Any(x => x.Item1 == "_type" && x.Item2 == resourceType);
         }
 
         private Expression<Predicate<IReadOnlyList<Tuple<string, string>>>> CreateQueryParametersExpressionWithContinuationToken(string continuationToken, string resourceType)
         {
             return arg => arg != null &&
-                Tuple.Create("_count", "1").Equals(arg[0]) &&
-                Tuple.Create("_lastUpdated", $"le{_exportJobRecord.Till}").Equals(arg[1]) &&
-                Tuple.Create("_type", resourceType).Equals(arg[2]) &&
-                Tuple.Create("ct", continuationToken).Equals(arg[3]);
+                arg.Any(x => x.Item1 == "_count" && x.Item2 == "1") &&
+                arg.Any(x => x.Item1 == "_lastUpdated" && x.Item2 == $"le{_exportJobRecord.Till}") &&
+                arg.Any(x => x.Item1 == "_type" && x.Item2 == resourceType) &&
+                arg.Any(x => x.Item1 == "ct" && x.Item2 == continuationToken);
         }
 
         private Expression<Predicate<IReadOnlyList<Tuple<string, string>>>> CreateQueryParametersExpressionWithContinuationToken(string continuationToken, PartialDateTime since, string resourceType)
         {
             return arg => arg != null &&
-                Tuple.Create("_count", "1").Equals(arg[0]) &&
-                Tuple.Create("_lastUpdated", $"le{_exportJobRecord.Till}").Equals(arg[1]) &&
-                Tuple.Create("_lastUpdated", $"ge{since}").Equals(arg[2]) &&
-                Tuple.Create("_type", resourceType).Equals(arg[3]) &&
-                Tuple.Create("ct", continuationToken).Equals(arg[4]);
+                arg.Any(x => x.Item1 == "_count" && x.Item2 == "1") &&
+                arg.Any(x => x.Item1 == "_lastUpdated" && x.Item2 == $"le{_exportJobRecord.Till}") &&
+                arg.Any(x => x.Item1 == "_lastUpdated" && x.Item2 == $"ge{since}") &&
+                arg.Any(x => x.Item1 == "_type" && x.Item2 == resourceType) &&
+                arg.Any(x => x.Item1 == "ct" && x.Item2 == continuationToken);
         }
 
         [Fact]
@@ -834,7 +867,9 @@ public async Task GivenAnExportJobWithTheTypeParameter_WhenExecuted_ThenOnlyReso
                 true)
                 .Returns(x =>
                 {
-                    string[] types = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)[3].Item2.Split(',');
+                    string[] types = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)
+                        .Where(x => x.Item1 == KnownQueryParameterNames.Type)
+                        .Select(x => x.Item2).First().Split(',');
                     SearchResultEntry[] entries = new SearchResultEntry[types.Length];
 
                     for (int index = 0; index < types.Length; index++)
@@ -889,7 +924,9 @@ public async Task GivenAPatientExportJobWithTheTypeParameter_WhenExecuted_ThenOn
                 true)
                 .Returns(x =>
                 {
-                    string[] types = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(3)[3].Item2.Split(',');
+                    string[] types = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(3)
+                        .Where(x => x.Item1 == KnownQueryParameterNames.Type)
+                        .Select(x => x.Item2).First().Split(',');
                     SearchResultEntry[] entries = new SearchResultEntry[types.Length];
 
                     for (int index = 0; index < types.Length; index++)
@@ -1107,7 +1144,9 @@ public async Task GivenAGroupExportJob_WhenExecuted_ThenAllPatientResourcesInThe
                 true)
                 .Returns(x =>
                 {
-                    string[] ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)[2].Item2.Split(',');
+                    string[] ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)
+                        .Where(x => x.Item1 == Core.Features.KnownQueryParameterNames.Id)
+                        .Select(x => x.Item2).First().Split(',');
                     SearchResultEntry[] entries = new SearchResultEntry[ids.Length];
 
                     for (int index = 0; index < ids.Length; index++)
@@ -1175,7 +1214,9 @@ public async Task GivenAGroupExportJobWithMultiplePagesOfPatients_WhenExecuted_T
                 true)
                 .Returns(x =>
                 {
-                    string[] ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)[2].Item2.Split(',');
+                    string[] ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)
+                        .Where(x => x.Item1 == KnownQueryParameterNames.Id)
+                        .Select(x => x.Item2).First().Split(',');
 
                     countOfSearches++;
 
@@ -1250,7 +1291,9 @@ public async Task GivenAGroupExportJobToResume_WhenExecuted_ThenAllPatientResour
 
                     if (countOfSearches == 1)
                     {
-                        ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)[2].Item2.Split(',');
+                        ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)
+                            .Where(x => x.Item1 == Core.Features.KnownQueryParameterNames.Id)
+                            .Select(x => x.Item2).First().Split(',');
                         continuationTokenIndex = 0;
                     }
                     else if (countOfSearches == 2)
@@ -1261,7 +1304,10 @@ public async Task GivenAGroupExportJobToResume_WhenExecuted_ThenAllPatientResour
                     {
                         // The ids aren't in the query parameters because of the reset
                         ids = new string[] { "1", "2", "3" };
-                        continuationTokenIndex = int.Parse(ContinuationTokenConverter.Decode(x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)[2].Item2).Substring(2));
+                        continuationTokenIndex = int.Parse(ContinuationTokenConverter.Decode(
+                            x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)
+                                .Where(x => x.Item1 == Core.Features.KnownQueryParameterNames.ContinuationToken)
+                                .Select(x => x.Item2).First())[2..]);
                     }
 
                     return CreateSearchResult(
@@ -1342,7 +1388,10 @@ public async Task GivenAGroupExportJobWithTheTypeParameter_WhenExecuted_ThenAllP
                 true)
                 .Returns(x =>
                 {
-                    string[] ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)[2].Item2.Split(',');
+                    string[] ids = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(1)
+                        .Where(x => x.Item1 == KnownQueryParameterNames.Id)
+                        .Select(x => x.Item2).First().Split(',');
+
                     SearchResultEntry[] entries = new SearchResultEntry[ids.Length];
 
                     for (int index = 0; index < ids.Length; index++)
@@ -1363,7 +1412,9 @@ public async Task GivenAGroupExportJobWithTheTypeParameter_WhenExecuted_ThenAllP
                 .Returns(x =>
                 {
                     string parentId = x.ArgAt<string>(1);
-                    string[] resourceTypes = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(3)[2].Item2.Split(',');
+                    string[] resourceTypes = x.ArgAt<IReadOnlyList<Tuple<string, string>>>(3)
+                        .Where(x => x.Item1 == KnownQueryParameterNames.Type)
+                        .Select(x => x.Item2).First().Split(',');
 
                     SearchResultEntry[] entries = new SearchResultEntry[resourceTypes.Length];
 
@@ -2076,7 +2127,9 @@ private ExportJobRecord CreateExportJobRecord(
             uint numberOfPagesPerCommit = 0,
             string containerName = null,
             string anonymizationConfigurationLocation = null,
-            string anonymizationConfigurationFileEtag = null)
+            string anonymizationConfigurationFileEtag = null,
+            bool includeHistory = false,
+            bool includeDeleted = false)
         {
             return new ExportJobRecord(
                 new Uri(requestEndpoint),
@@ -2094,7 +2147,9 @@ private ExportJobRecord CreateExportJobRecord(
                 numberOfPagesPerCommit: numberOfPagesPerCommit == 0 ? _exportJobConfiguration.NumberOfPagesPerCommit : numberOfPagesPerCommit,
                 storageAccountContainerName: containerName,
                 anonymizationConfigurationLocation: anonymizationConfigurationLocation,
-                anonymizationConfigurationFileETag: anonymizationConfigurationFileEtag);
+                anonymizationConfigurationFileETag: anonymizationConfigurationFileEtag,
+                includeHistory: includeHistory,
+                includeDeleted: includeDeleted);
         }
 
         private ExportJobTask CreateExportJobTask(

src/Microsoft.Health.Fhir.Core/Configs/ExportJobConfiguration.cs

@@ -42,6 +42,16 @@ public class ExportJobConfiguration
         /// </summary>
         public uint MaximumNumberOfResourcesPerQuery { get; set; } = 10000;
 
+        /// <summary>
+        /// For SQL export, controlls the number of parallel id ranges to gather to be used for parallel export.
+        /// </summary>
+        public int NumberOfParallelRecordRanges { get; set; } = 100;
+
+        /// <summary>
+        /// For SQL export, controlls the DOP (degree of parallelization) used by the coordinator to build sub-jobs.
+        /// </summary>
+        public int CoordinatorMaxDegreeOfParallelization { get; set; } = 4;
+
         /// <summary>
         /// Number of pages to be iterated before committing the export progress.
         /// </summary>

src/Microsoft.Health.Fhir.Core/Extensions/ExportMediatorExtensions.cs

@@ -28,6 +28,8 @@ public static async Task<CreateExportResponse> ExportAsync(
             string containerName,
             string formatName,
             bool isParallel,
+            bool includeDeleted,
+            bool includeHistory,
             uint maxCount,
             string anonymizationConfigurationCollectionReference,
             string anonymizationConfigLocation,
@@ -37,7 +39,23 @@ public static async Task<CreateExportResponse> ExportAsync(
             EnsureArg.IsNotNull(mediator, nameof(mediator));
             EnsureArg.IsNotNull(requestUri, nameof(requestUri));
 
-            var request = new CreateExportRequest(requestUri, requestType, resourceType, since, till, filters, groupId, containerName, formatName, isParallel, maxCount, anonymizationConfigurationCollectionReference, anonymizationConfigLocation, anonymizationConfigFileETag);
+            var request = new CreateExportRequest(
+                                requestUri: requestUri,
+                                requestType: requestType,
+                                resourceType: resourceType,
+                                since: since,
+                                till: till,
+                                filters: filters,
+                                groupId: groupId,
+                                containerName: containerName,
+                                formatName: formatName,
+                                isParallel: isParallel,
+                                maxCount: maxCount,
+                                includeDeleted: includeDeleted,
+                                includeHistory: includeHistory,
+                                anonymizationConfigurationCollectionReference: anonymizationConfigurationCollectionReference,
+                                anonymizationConfigurationLocation: anonymizationConfigLocation,
+                                anonymizationConfigurationFileETag: anonymizationConfigFileETag);
 
             CreateExportResponse response = await mediator.Send(request, cancellationToken);
             return response;

src/Microsoft.Health.Fhir.Core/Features/KnownQueryParameterNames.cs

@@ -99,6 +99,24 @@ public static class KnownQueryParameterNames
 
         public const string PurgeHistory = "_purgeHistory";
 
+        /// <summary>
+        /// Used by queries from the $export mediator to signal that history should be included in the export search.
+        /// </summary>
+        public const string IncludeHistory = "_includeHistory";
+
+        /// <summary>
+        /// Used by queries from the $export mediator to signal that soft deleted resources should be included in the export search.
+        /// </summary>
+        public const string IncludeDeleted = "_includeDeleted";
+
+        /// <summary>
+        /// Used by $export as a comma-separated list of parameters instructing which initial data should be included.
+        /// </summary>
+        public const string IncludeAssociatedData = "includeAssociatedData";
+
+        /// <summary>
+        /// Used by export to specify the number of resources to be processed by the search engine.
+        /// </summary>
         public const string MaxCount = "_maxCount";
     }
 }