SYSTEM_TIME CONTAINED IN zwraca wyłącznie wersje wiersza całkowicie mieszczące się we wskazanym okresie.
Jak działa SYSTEM_TIME CONTAINED IN w tabelach temporalnych SQL Server
SYSTEM_TIME CONTAINED IN jest predykatem temporalnym języka T-SQL używanym przy odczycie tabel systemowo wersjonowanych w Microsoft SQL Server. Składnia ma postać FOR SYSTEM_TIME CONTAINED IN (początek, koniec) i pozwala pobrać te wersje wierszy, których cały okres obowiązywania mieści się we wskazanym przedziale czasu. Nie wystarczy więc, że wersja tylko częściowo nakłada się na ten przedział.
W tabeli temporalnej SQL Server każda wersja wiersza ma okres ważności opisany przez dwie kolumny okresu, zwykle definiowane jako ValidFrom i ValidTo. Kolumny te są oznaczane definicją PERIOD FOR SYSTEM_TIME, a ich wartości są zarządzane przez silnik bazy danych. Dla wersji historycznej początek okresu wskazuje moment rozpoczęcia obowiązywania danych, natomiast koniec oznacza moment ich zastąpienia albo usunięcia. Warunek CONTAINED IN porównuje właśnie te granice z zakresem podanym w zapytaniu.
Warunek pełnego zawarcia przedziału wersji
Załóżmy, że zapytanie używa zakresu od 2025-01-01 do 2025-02-01. Wersja z okresem 2025-01-10–2025-01-20 zostanie zwrócona, ponieważ w całości znajduje się pomiędzy obiema granicami. Wersja rozpoczynająca się 2024-12-28 i kończąca 2025-01-10 nie spełni tego warunku, mimo że jej część przypada na wyszukiwany okres. Tak samo odrzucona zostanie wersja rozpoczynająca się w styczniu, ale kończąca się po 2025-02-01.
W praktyce można to rozumieć jako logiczny warunek odnoszący się do kolumn okresu: początek wersji musi przypadać nie wcześniej niż początek zakresu, a koniec wersji nie później niż koniec zakresu. Wewnętrzne wersje wiersza są więc wybierane na podstawie pełnego zamknięcia ich okresu w zadanym przedziale, a nie na podstawie dowolnego przecięcia osi czasu. Ma to znaczenie przy analizie zmian, ponieważ wynik nie zawiera rekordów, których historia wykracza poza badany zakres.
Składnia zapytania i granice czasu
Przykładowe zapytanie dla tabeli dbo.Laptopy może wyglądać następująco:
SELECT NumerSeryjny, Status, ValidFrom, ValidTo
FROM dbo.Laptopy
FOR SYSTEM_TIME CONTAINED IN ('2025-01-01T00:00:00', '2025-02-01T00:00:00');
Zapytanie dotyczy tabeli temporalnej i jej historii, dlatego nie trzeba wykonywać osobnego połączenia z tabelą historii. SQL Server interpretuje literały czasu zgodnie z typem kolumn okresu, który w systemowo wersjonowanych tabelach temporalnych jest oparty na typie datetime2. Warto podawać datę i godzinę w jednoznacznym formacie ISO, na przykład 2025-01-01T00:00:00, oraz uwzględniać precyzję zdefiniowaną dla kolumn okresu.
Zakres przekazywany do CONTAINED IN powinien mieć poprawne granice chronologiczne. Jeżeli początek jest późniejszy od końca, zapytanie nie opisuje prawidłowego przedziału i może zakończyć się błędem albo nie dostarczyć oczekiwanego wyniku zależnie od użytej składni i wartości. Warto również pamiętać, że wynik obejmuje wersje spełniające kryterium czasowe, a nie tylko aktualny stan logicznego wiersza. Jeden identyfikator może zatem pojawić się wiele razy, jeżeli w wybranym okresie istniało kilka kolejnych wersji tego samego rekordu.
Różnica między CONTAINED IN a innymi zapytaniami temporalnymi
CONTAINED IN nie jest odpowiednikiem zapytania pokazującego stan tabeli na określony moment. Do odczytu wersji obowiązującej w jednej chwili służy FOR SYSTEM_TIME AS OF. Z kolei FROM ... TO zwraca wersje, które obowiązywały w określonym przedziale, a BETWEEN ... AND stosuje podobne kryterium z inną interpretacją granicy końcowej. Predykat CONTAINED IN jest przeznaczony do wyszukiwania wersji całkowicie zawartych w zakresie.
Przy diagnozowaniu historii danych w SQL Server trzeba rozróżnić czas systemowy od czasu biznesowego zapisanego w zwykłej kolumnie, na przykład DataZgloszenia. CONTAINED IN filtruje okres systemowy zdefiniowany przez PERIOD FOR SYSTEM_TIME, a nie dowolną datę znajdującą się w treści rekordu. Jeżeli wynik jest pusty, przyczyną może być brak wersji całkowicie mieszczących się w zakresie, zbyt wąskie granice czasu, inna strefa czasowa użyta przy interpretacji danych albo zapytanie skierowane do tabeli, która nie jest skonfigurowana jako systemowo wersjonowana.
Podczas diagnostyki tabel temporalnych należy sprawdzić definicję kolumn okresu, nazwę tabeli historii oraz wartości ValidFrom i ValidTo dla zwracanych rekordów. Takie porównanie pozwala potwierdzić, czy filtr działa zgodnie z założeniem i czy analizowany zakres obejmuje pełne wersje wierszy. W przypadku problemu z wynikami naprawa może polegać na skorygowaniu granic zapytania lub czasu użytego przez aplikację, a nie na modyfikowaniu danych historycznych.
