/Notes-server

Server side for a final project of Databases 2 university course

Primary LanguageC#

Notes - Dokumentacja projektu zaliczeniowego z przedmiotu Bazy Danch 2

1. Opis projektu

Temat:

Przetwarzanie danych typu CLOB. Opracować API i jego implementację do przetwarzania danych typu CLOB. W ramach projektu można wykorzystać typ danych CLOB oraz technologię wyszukiwania pełnotekstowe FTS. Opracowane API powinno umożliwić zapis i usunięcie wybranego dokumentu oraz wyszukanie określonej informacji w dokumentach umieszczonych w repozytorium.

Wprowadzenie teoretyczne

W SQL Server dane typu CLOB przetrzymywane są za pomocą typu nvarchar(max), który może przechowywać do 2GB danych tekstowych. Przeszukiwania pełnotekstowe (Full-Text Search) są wykonywane na indeksach pełnotekstowych (Full-Text Index) a więc aby umożliwić wykonywanie takich zapytań najpierw należy zadbać o utworzenie takiego indeksu.

Indeks pełnotekstowy to specjalna forma indeksu, która przechowywana jest w specjalnym wirtualnym kontenerze zwanym katalogiem pełnoteksowym (Full-Text Catalog). Jeden katalog może zawierać wiele indeksów ale jeden indeks może należeć tylko do jednego katalogu. Kolejnym ograniczeniem jest tylko jeden indeks pełnotekstowy dla tabeli.

Zapytania pełnotekstowe (Full-Text Query) mogą dotyczyć między innymi:

  • jednego lub więcej konkretnych słów,
  • słów rozpoczynających się od określonego tekstu (prefiksy)
  • form fleksyjnych słowa, np dla słowa: drzwi: drzwi, drzwiom, drzwiami i drzwiach
  • słów zbliżonych do zadanego wyrażenia
  • synonimów

Dla FTS nie jest rozróżniana wielkość liter a realizację zapytań wykonujemy poprzez niewielki zestaw predykatów: CONTAINS, FREETEXT (T-SQL) oraz CONTAINSTABLE i FREETEXTTABLE (funkcje).

Propozycja rozwiązania:

Notes - Aplikacja webowa służąca do zarządzania i przeglądnaia notatek, które są pogrupowane na różne przedmioty. REST API udostępnia operacje do zarządzania przedmiotami oraz notatkami. Opcja wyszukiwania notatek zawierających zadaną frazę (FTS).

DEMO APLIKACJI => LINK*

UWAGA !!!

Z racji darmowego hostingu na Azure, backend aplikacji potrzebuje chwili na rozruch po okresie uśpienia więc przy pierwszym wejściu należy chwilę poczekać na załadowanie danych.

2. Endpointy i typy danych

Poniższe zdjęcie pochodzące z narzędzia go automatycznego generowania dokumentuji do API - Swagger - przedstawia endpointy wystawione przez serwer:

image

Dane zwracane w zapytaniach typu GET kształtują się zgodnie ze zdefiniowanymi w projekcie klasami, zaprezentowanymi w uproszczeniu na zdjęciu poniżej. W przypadku endpointów zakończonych parametrem {id} zwracane są pojedyncze obiekty odpowiedniego typu a w przypadku zapytań GET o ogólnej formie np. /Subject lub /Subject/{id}/Notes zwracane są listy obiektów.

class Subject {
  int Id;
  string Name;
  string Description;
}

class Note {
  int Id;
  string Title;
  string Content;
  DateTime CreatedAt;
  int SubjectId;
}

Przedstawione powyżej klasy określające typy danych, są automatycznie mapowane na tabele w bazie danych dzięki uprzejmości frameworka Entity Framework.

Jeśli chodzi o dane oczekiwane w zapytaniach typu POST opisane są przez specjalne klasy DTO (Data Transfer Object):

class SubjectDTO {
  string Name;
  string Description;
}

class NoteDTO {
  string Title;
  string Content;
  int SubjectId;
}

3. Opis implementacji

3.2 Baza Danych

Wykorzystaną bazą danych jest oczywiście SQL Server 2019. Z racji specyfiki wybranego tematu projektu niezbędne jest rownież doinstalowanie dodatkowej usługi Full-Text Search.

W strukturze bazy danych występują jedynie dwie tabele: Subjects oraz Notes, połączone relacją jeden do wielu.

Full-Text Index utworzony został dla kolumny Content tabeli Notes, która przechowuje właściwe treści przechowywanych notatek czy definicji, które mogą osiągać znaczne rozmiary.

W celu utworzenia indeksu pełnotekstowego stworzony został najpierw katalog pełnotekstowy notes_catalog:

CREATE FULLTEXT CATALOG [notes_catalog] WITH ACCENT_SENSITIVITY = ON
AS DEFAULT

a następnie na tym katalogu dodany został wspomniany indeks:

CREATE FULLTEXT INDEX ON [dbo].[Notes]
    ([Content] LANGUAGE 2057)
    KEY INDEX [PK_Notes]
    ON [notes_catalog];

3.2 Serwer

Serwerowa część apliakcji zaimplementowała została w technologii ASP.NET Core 5.0 jako REST API. Struktura projetu jest typowa dla tego rodzaju aplikacji - występuje podział na kontrolery, które odpowiadają za routing i obsługę zapytań na najwyższym poziomie abstrakcji i realizują zadane fragmenty API (np. opracje na notatkach czy przedmiotach)

Operacje na bazie danych, a dokładnie na jej kontekście (DbContext) wykonywane są z poziomu repozytoriów, które obsługują konkretne rodzaje zapytań i są wykorzystywane w kontrolerach.

Jako że projekt jest bardzo mały, podjęto decyzję aby nie wprowadzać dodatkowej warstwy abstrakcji pomiędzy kontrolerami a repozytoriami (serwisy).

Repozytorium z kodem serwera

3.3 Klient

Jako klienta stworzonego API webowgo zaproponowano prosty prototyp aplikacji webowej napisany przy użyciu biblioteki React. Aplikacja posiada jedynie trzy widoki: główny - prezentujący dostępne przedmioty, widok konkretnego przedmiotu z widoczynmi odnoszącymi się do niego notatkami oraz informacyjny - zawierajacy podstawowe informacje o aplikacji oraz linki.

Repozytorium z kodem klienta

4. Testy

Z racji tworzenia w ramach projektu API webowego typu REST skupiono się na testach integracyjnych, testujących działanie dostępnych endpointów. Poniżej zamieszczony został screen shot z rezultatem uruchomienia testów serwerowej części projektu:

image

5. Interfejs Aplikacji

Strona główa, przedstawiająca dostepne przedmioty, do których przypisane są poszczególne notatki:

image

Strona konkretnego przedmiotu z listą notatek oraz polem do wyszukiwania tekstowego na zawartości notatek:

image

Widok konkretnej notatki, z zaznaczonymi wystąpieniami szukanej frazy (o ile została ona podana):

image

Podstrona informacyjna:

image

Forumlarz do dodawania notatek:

image

6. Lokalne uruchomienie projektu

6.1 Serwer

Wymagania:

  • Visual Studio 2019 ze wsparciem dla .NET 5.0
  • MSSQL Server 2019 z zainstalowanym dodatkem do obsługi Full-Text Search

Instrukcje:

  1. Sklonować repozytorium z kodem źródłowym:
$ git clone https://github.com/Fadikk367/Notes-server.git

  1. Uruchomić skrypty sql z katalogu /sql w podanej kolejności w celu utworzenia bazy danych wraz z niezbędną strukturą oraz przykładowymi danymi

  2. Uruchomić projekt w środowisku Visual Studio 2019

API zostanie wystawione pod adresem:

http://localhost:28410

6.2 Klient

Wymagania:

  • Node.js v14+

Instrukcje:

  1. Sklonować repozytorium z kodem źródłowym:
$ git clone https://github.com/Fadikk367/Notes-client.git
  1. Z poziomu katalogu głównego wywołać komendę:
$ npm install
  1. Następnie:
$ npm start

Aplikacja zostanie uruchomiona na lokalnym porcie 3000:

http://localhost:28410

7. Podsumowanie

Technologia Full-Text Search pozwala na wydajne przeszukiwanie danych tekstowych (w tym CLOB) pod kątem występowania danych słów czy fraz. W porównaniu do operatora LIKE, FTS wypada znacznie lepiej, tymbardziej jeśli mamy do czynienia ze znacznymi ilościami rekordów zawierających dane tekstowe. Aby móc wdrożyć tą technologię do swojej bazy danych należy zadbać o instalację dodatkowego komponentu FullText Search.

W zaprezentowanej aplikacji FTS została wykorzystana w celu przeszukiwania dostępnych notatek pod kątem pożądanych słów kluczowych czy nawet występowania całych fraz.

8. Źródła