Otwieranie wymagań i formatu strefy docelowej dublowania

W tym artykule szczegółowo przedstawiono wymagania dotyczące operacji strefy docelowej i tabeli/kolumny dotyczące otwierania dublowania w usłudze Microsoft Fabric.

Po utworzeniu otwartej dublowanej bazy danych za pośrednictwem portalu sieci szkieletowej lub publicznego interfejsu API w obszarze roboczym usługi Fabric otrzymasz adres URL strefy docelowej w usłudze OneLake na stronie głównej elementu dublowanej bazy danych. Ta strefa docelowa to miejsce, w którym aplikacja tworzy plik metadanych i dane lądowe w formacie Parquet lub rozdzielanym tekstem, w tym CSV. Pliki mogą być nieskompresowane lub kompresowane za pomocą przystawki, GZIP lub ZSTD. Aby uzyskać więcej informacji, zobacz obsługiwane pliki danych i format.

Strefa docelowa

Dla każdej bazy danych z lustrzanym odbiciem istnieje unikalne miejsce przechowywania w usłudze OneLake dla metadanych i tabel różnicowych. Otwieranie dublowania udostępnia folder strefy docelowej dla aplikacji w celu utworzenia pliku metadanych i wypychania danych do usługi OneLake. Dublowanie monitoruje te pliki w strefie docelowej i odczytuje folder dla nowych tabel i dodanych danych.

Jeśli na przykład masz tabele (Table A, Table B, Table C), które mają zostać utworzone w strefie docelowej, utwórz foldery podobne do następujących adresów URL:

• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableA
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableB
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableC

Plik metadanych w strefie docelowej

Każdy folder tabeli musi zawierać _metadata.json plik.

Ten plik metadanych tabeli zawiera rekord JSON, który obecnie określa tylko unikatowe kolumny klucza jako keyColumns.

Aby na przykład zadeklarować kolumny C1 i C2 jako unikatowy klucz złożony dla tabeli:

{
   "keyColumns" : ["C1", "C2"]
}

Jeśli keyColumns lub _metadata.json nie zostaną określone, aktualizacje/usunięcia nie są możliwe. Ten plik można dodać w dowolnym momencie, ale po dodaniu keyColumns nie można go zmienić.

Plik zdarzeń w strefie docelowej

Jeśli jesteś partnerem wdrażającym otwarte rozwiązanie replikacji lub klientem, który chce podać nam więcej szczegółów na temat typu źródła, które jest replikowane do OneLake, dodaliśmy nowy plik _partnerEvents.json. Nie jest to wymagane, ale zdecydowanie zalecane.

Przykład:

{
  "partnerName": "testPartner",
  "sourceInfo": {
    "sourceType": "SQL",
    "sourceVersion": "2019",
    "additionalInformation": {
      "testKey": "testValue"
    }
  }
}

Wymagania dotyczące _partnerEvents.json pliku:

• Plik _partnerEvents.json powinien zostać umieszczony na poziomie dublowanej bazy danych w strefie docelowej, a nie na tabelę.
• Może sourceType to być dowolny ciąg opisowy reprezentujący źródło. Nie ma żadnych ograniczeń dotyczących tej wartości, na przykład: "SQL", "Oracle", "Salesforce" itp.
• partnerName Można ustawić dowolną nazwę wybranej nazwy i być reprezentatywną dla nazwy organizacji. Zachowaj spójność nazw we wszystkich dublowaniach baz danych.

Plik danych i format w strefie docelowej

Funkcja otwórz dublowanie obsługuje wprowadzanie danych w formatach tekstowych parquet lub rozdzielonych. Pliki mogą być nieskompresowane lub kompresowane za pomocą przystawki, GZIP lub ZSTD.

Wymagania parquet

Wymagania dotyczące tekstu rozdzielanego

• W przypadku formatu tekstu rozdzielanego plik musi mieć wiersz nagłówka w pierwszym wierszu.

• W przypadku tekstu rozdzielanego podaj dodatkowe informacje w _metadata.json pliku. Właściwość jest wymagana FileExtension . Rozdzielane pliki tekstowe mają następujące właściwości i wartości domyślne:

  Majątek	Description	Notatki
  FirstRowAsHeader	Prawda/fałsz dla nagłówka pierwszego wiersza.	Wymagane do obsługi true rozdzielanych plików tekstowych.
  RowSeparator	Znak używany do oddzielania wierszy.	Wartość domyślna to \r\n. Obsługuje również programy \n i \r.
  ColumnSeparator	Znak używany do oddzielania kolumn.	Wartość domyślna to ,. Obsługuje również elementy ;, |i \t.
  QuoteCharacter	Znak używany do cudzysłowu zawierającego ograniczniki.	Wartość domyślna to ". Może również być ' lub pusty ciąg.
  EscapeCharacter	Służy do ucieczki cudzysłowów wewnątrz cytowanych wartości.	Wartość domyślna to \. Może to być /również wartość , "lub pusta.
  NullValue	Reprezentacja ciągu wartości null.	Może to być "", "N/A", "null"itp.
  Encoding	Kodowanie znaków pliku.	Wartość domyślna to UTF-8. Obsługuje szeroką gamę kodowań, w tym ascii, utf-16, windows-1252itp.
  SchemaDefinition	Definiuje nazwy kolumn, typy i wartość null.	Ewolucja schematu nie jest obsługiwana.
  FileFormat	Format pliku danych.	Wartość domyślna to CSV , jeśli nie zostanie określona. Musi być "DelimitedText" przeznaczony dla formatów innych niż CSV.
  FileExtension	Określa rozszerzenie pliku, takie jak .tsv, .psv.	Wymagane w przypadku używania polecenia DelimitedText.

  Na przykład _metadata.json plik dla .tsv pliku danych z czterema kolumnami:

  {
  "KeyColumns": [ "id" ],
  "SchemaDefinition": {
      "Columns": [
                    {
                    "Name": "id",
                    "DataType": "Int32"
                    },
                    {
                    "Name": "name",
                    "DataType": "String",
                    "IsNullable": true
                    },
                    {
                    "Name": "age",
                    "DataType": "Int32",
                    "IsNullable": true
                    },
                    {
                    "Name": "seqNum",
                    "DataType": "Int64",
                    "IsNullable": false
                    }
                  ]
                },
  "FileFormat": "DelimitedText",
  "FileExtension": "tsv",
  "FileFormatTypeProperties": {
                              "FirstRowAsHeader": true,
                              "RowSeparator": "\r\n",
                              "ColumnSeparator": ",",
                              "QuoteCharacter": "'",
                              "EscapeCharacter": "\",
                              "NullValue": "N/A",
                              "Encoding": "UTF-8"
                           }
  }
  

• Oczekuje się, że tylko rozdzielane formaty tekstu mają typ danych w pliku _metadata.json. Pliki Parquet nie muszą określać informacji o typie kolumny. Obecnie obsługiwane typy danych:

Wymagania dotyczące formatu

Wszystkie pliki zapisane w strefie docelowej mają następujący format:

<rowMarker><DataColumns>

• rowMarker: nazwa kolumny to __rowMarker__ (w tym dwa podkreślenia przed i po rowMarker). __rowMarker__ wartości i zachowania:

  __rowMarker__ (Scenariusz)	Jeśli wiersz nie istnieje z tymi samymi kolumnami kluczy w miejscu docelowym	Jeśli wiersz istnieje z tymi samymi kolumnami kluczy w miejscu docelowym
  0 (Wstaw)	Wstaw wiersz do miejsca docelowego	Wstaw wiersz do miejsca docelowego, bez sprawdzania poprawności pod kątem sprawdzania kolumny klucza dup.
  1 (Aktualizacja)	Wstaw wiersz do miejsca docelowego, bez sprawdzania poprawności/wyjątku w celu sprawdzenia istnienia wiersza z tą samą kolumną klucza.	Zaktualizuj wiersz przy użyciu tej samej kolumny klucza.
  2 (Usuń)	Brak zmian danych, brak walidacji/wyjątku w celu sprawdzenia istnienia wiersza z tą samą kolumną klucza.	Usuń wiersz z tą samą kolumną klucza.
  4 (Upsert)	Wstaw wiersz do miejsca docelowego, bez sprawdzania poprawności/wyjątku w celu sprawdzenia istnienia wiersza z tą samą kolumną klucza.	Zaktualizuj wiersz przy użyciu tej samej kolumny klucza.

• Kolejność wierszy: wszystkie dzienniki w pliku powinny być w naturalnej kolejności, zgodnie z zastosowaniem transakcji. Jest to ważne w przypadku tego samego wiersza aktualizowanego wiele razy. Otwieranie dublowania stosuje zmiany przy użyciu kolejności w plikach.

• Kolejność plików: pliki powinny być dodawane w monotonicznie rosnącej liczbie.

• Nazwa pliku: Nazwa pliku to 20 cyfr, na przykład 00000000000000000001.parquet dla pierwszego pliku, a 00000000000000000002.parquet drugi. Nazwy plików powinny być w liczbach ciągłych. Pliki zostaną usunięte automatycznie przez usługę dublowania, ale ostatni plik zostanie pozostawiony, aby system wydawcy mógł odwoływać się do niego w celu dodania następnego pliku w sekwencji.

Pliki niesekwencyjne

Obsługiwane są również pliki niekwercyjne; pliki będą odczytywane na podstawie sygnatury czasowej. Aby określić to i ustawić domyślne działanie na upsertowanie zmian zamiast wstawiania, zaktualizuj plik _metadata.json w następujący sposób:

{
   "keyColumns" : ["id"],
   "fileDetectionStrategy": LastUpdateTimeFileDetection,
   "isUpsertDefaultRowMarker": true
}

Domyślne ustawienie opcji upsert nie zależy od plików niesekwencyjnych. Obsługiwane są wszystkie następujące kombinacje:

• Ustawić właściwość fileDetectionStrategy jako LastUpdateTimeFileDetection oraz isUpsertDefaultRowMarker jako true.
• Mieć tylko isUpsertDefaultRowMarker ustawione na true.
• Jest tylko fileDetectionStrategy jako LastUpdateTimeFileDetection.
• Default

Ładowanie początkowe

W przypadku początkowego ładowania danych do otwartej dublowanej bazy danych __rowMarker__ w początkowym pliku danych jest opcjonalny i nie jest zalecany. Dublowanie traktuje cały plik jako wstawkę, gdy __rowMarker__ nie istnieje.

Aby uzyskać lepszą wydajność i dokładne metryki, __rowMarker__ jest obowiązkowym polem tylko dla zmian przyrostowych w celu zastosowania operacji update/delete/upsert.

Zmiany przyrostowe

Otwieranie funkcji dublowania odczytuje przyrostowe zmiany w kolejności i stosuje je do docelowej tabeli delty. Kolejność jest niejawna w dzienniku zmian i w kolejności plików.

Zmiany danych są uznawane za zmiany przyrostowe po znalezieniu __rowMarker__ kolumny z dowolnego wiersza/pliku.

Zaktualizowane wiersze muszą zawierać pełne dane wierszy ze wszystkimi kolumnami.

Oto kilka przykładowych danych parquet dotyczących historii rekordu, aby zmienić EmployeeLocation wartość dla EmployeeID E0001 z Redmond na Bellevue. W tym scenariuszu kolumna EmployeeID została oznaczona jako kolumna klucza w pliku metadanych w strefie docelowej.

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Redmond,0
E0002,Redmond,0
E0003,Redmond,0
E0001,Bellevue,1

Jeśli kolumny kluczy zostaną zaktualizowane, powinien zostać wyświetlony przez polecenie DELETE w poprzednich kolumnach kluczy i wiersze INSERT z nowym kluczem i danymi. Na przykład historia wierszy, aby zmienić __rowMarker__ unikatowy identyfikator E0001 EmployeeID na E0002. Nie musisz podawać wszystkich danych kolumn dla wiersza DELETE, tylko kolumn kluczy.

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Bellevue,0
E0001,NULL,2
E0002,Bellevue,0

Operacje na tabelach

Funkcja otwierania dublowania obsługuje operacje tabel, takie jak dodawanie, usuwanie i zmienianie nazw tabel.

Dodawanie tabeli

Otwieranie funkcji dublowania pobiera dowolną tabelę dodaną do strefy docelowej przez aplikację. Otwórz skanowanie dublowania dla nowych tabel w każdej iteracji.

Upuść tabelę

Otwieranie dublowania śledzi nazwę folderu. Jeśli folder tabeli zostanie usunięty, otwórz dublowanie pomiń tabelę w dublowanej bazie danych.

Jeśli folder zostanie utworzony ponownie, otwórz dublowanie pomiń tabelę i ponownie utworzy ją przy użyciu nowych danych w folderze, wykonując śledzenie elementu ETag dla folderu.

Podczas próby usunięcia tabeli możesz spróbować usunąć folder, ale istnieje prawdopodobieństwo, że otwieranie dublowania nadal używa danych z folderu, powodując niepowodzenie usuwania dla wydawcy.

Zmienianie nazwy tabeli

Aby zmienić nazwę tabeli, upuść i ponownie utwórz folder przy użyciu danych początkowych i przyrostowych. Dane muszą być ponownie wypełniane do zmienionej tabeli.

Schema

Ścieżkę tabeli można określić w folderze schematu. Strefa docelowa <schemaname>.schema schematu powinna mieć nazwę folderu. Może istnieć wiele schematów i może istnieć wiele tabel w schemacie.

Jeśli na przykład masz schematy (, Schema1) i tabele (Schema2Table A, Table B, Table C), które mają zostać utworzone w strefie docelowej, utwórz foldery podobne do następujących ścieżek w usłudze OneLake:

• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableA
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableB
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema2.schema/TableC

Kolumny tabeli i operacje kolumn

Typy kolumn

• Proste typy parquet są obsługiwane w strefie docelowej.
• Typy złożone powinny być zapisywane jako ciąg JSON.
• Typy złożone binarne, takie jak geografia, obrazy itp., mogą być przechowywane jako typ binarny w strefie docelowej.

Dodawanie kolumny

Jeśli nowe kolumny są dodawane do plików parquet lub CSV, otwórz dublowanie dodaje kolumny do tabel różnicowych.

Usuń kolumnę

Jeśli kolumna zostanie porzucona z nowych plików dziennika, otwórz magazyny NULL dublowania dla tych kolumn w nowych wierszach, a stare wiersze mają kolumny obecne w danych. Aby usunąć kolumnę, usuń tabelę i ponownie utwórz folder tabeli w strefie docelowej, co spowoduje odtworzenie tabeli delty z nowym schematem i danymi.

Otwarte dublowanie zawsze składa wszystkie kolumny z poprzedniej wersji dodanych danych. Aby usunąć kolumnę, utwórz ponownie tabelę/folder.

Zmienianie typu kolumny

Aby zmienić typ kolumny, upuść i ponownie utwórz folder z początkowymi i przyrostowymi danymi o nowym typie kolumny. Podanie nowego typu kolumny bez ponownego utworzenia tabeli powoduje wystąpienie błędu, a replikacja dla tej tabeli zostanie zatrzymana. Po ponownym utworzeniu folderu tabeli replikacja zostanie wznowiona przy użyciu nowych danych i schematu.

Zmienianie nazwy kolumny

Aby zmienić nazwę kolumny, usuń folder tabeli i ponownie utwórz folder ze wszystkimi danymi i nową nazwą kolumny.

Proces oczyszczania

Proces oczyszczania podczas otwierania dublowania przenosi wszystkie przetworzone pliki do oddzielnego folderu o nazwie _ProcessedFiles lub _FilesReadyToDelete. Po siedmiu dniach pliki zostaną usunięte z tego folderu.

Następny krok

Treści powiązane

• Monitorowanie replikacji mirrorowanej bazy danych Fabric