getting started lesson 6

getting_started/Makefile

@@ -0,0 +1,7 @@
+runproject:
+	terminusdb commit
+	terminusdb importcsv Employees.csv --classname EmployeesFromCSV --id "Employee id" -e Manager -m "Import Employees from CSV"
+	python insert_data.py
+	python update_data.py
+	terminusdb branch contractors
+	python add_contractors.py

getting_started/add_contractors.py

@@ -0,0 +1,48 @@
+from terminusdb_client import WOQLClient
+from terminusdb_client.woqlschema import WOQLSchema
+
+# For Terminus X, use the following
+# client = WOQLClient("https://cloud.terminusdb.com/<Your Team>/")
+# client.connect(db="demo_workshop", team="<Your Team>", use_token=True)
+
+client = WOQLClient("http://127.0.0.1:6363/")
+client.connect(db="getting_started", branch="contractors")
+
+data_schema = WOQLSchema()
+data_schema.from_db(client)
+
+Employee = data_schema.object.get("Employee")
+Address = data_schema.object.get("Address")
+Team = data_schema.object.get("Team")
+
+# Contractor 1
+
+rhys_address = Address(
+    postcode="DG4 2ZQ", street="Helland Bridge", street_num=1, town="Ulzieside"
+)
+
+rhys = Employee(
+    _id="Employee/006",
+    name="Rhys Arnold",
+    title="UX Designer",
+    team=Team.it,
+    contact_number="078 3951 7569",
+    address=rhys_address,
+)
+
+# Contractor 2
+
+maya_address = Address(
+    postcode="GU3 3AF", street="Tadcaster Rd", street_num=24, town="Pitch Place"
+)
+
+maya = Employee(
+    _id="Employee/007",
+    name="Maya O'Brien",
+    title="Creative Content Creator",
+    team=Team.marketing,
+    contact_number="078 1788 9177",
+    address=maya_address,
+)
+
+client.update_document([rhys, maya], commit_msg="Adding contractors")

getting_started/insert_data.py

@@ -48,4 +48,4 @@
 client = WOQLClient("http://127.0.0.1:6363/")
 client.connect(db="getting_started")
 
-client.insert_document(list(employees.values()))
+client.insert_document(list(employees.values()), commit_msg="Adding 4 Employees")

getting_started/lesson_3.md

@@ -115,7 +115,7 @@ If you are using TerminusX, you can find the information of your endpoint, team,
 Now we are all ready, the last thing to do is to insert the documents:
 
 ```python
-client.insert_document(list(employees.values()))
+client.insert_document(list(employees.values()), commit_msg="Adding 4 Employees")
 ```
 
 ## Running the script

getting_started/lesson_4.md

@@ -59,7 +59,7 @@ destiny.address.town = "Newbigging"
 Let's send `destiny` back to the database with `update_document`, the difference between `insert_document` and `update_document` is that, is an object(s) is already exist, `update_docuemnt` with replace the old with the new. It will also insert the document if it does not exist:
 
 ```python
-client.update_document(destiny)
+client.update_document(destiny, commit_msg="Update Destiny")
 ```
 
 ## Linking a new document to an old document
@@ -104,15 +104,19 @@ ethan = Employee(
 All is ready, let's put `ethan` into the database. To prove `update_document` will also work, we will use it to insert `ethan`:
 
 ```python
-client.update_document(ethan)
+client.update_document(ethan, commit_msg="Adding Ethan")
 ```
 
 Or if you like, you can update `destiny` and insert `ethan` all at once like this:
 
 ```python
-client.update_document([destiny, ethan])
+client.update_document([destiny, ethan], commit_msg="Update Destiny and adding Ethan")
 ```
 
+Run the scripts:
+
+`$ python update_data.py`
+
 To check if the database is up-to-date, you can do in the terminal like we did before:
 
 `$ terminusdb alldocs`

getting_started/lesson_5.md

@@ -43,7 +43,7 @@ $ terminusdb alldocs --type Employee -q team=it
 [{'@id': 'Employee/003', '@type': 'Employee', 'address': {'@id': 'Address/543050aaa73c4590b38f9aed129b17ff', '@type': 'Address', 'postcode': 'BD18 2PT', 'street': 'Otley Road', 'street_num': 139, 'town': ' Shipley'}, 'contact_number': '(01274) 708080', 'manager': 'Employee/004', 'name': 'Alanah Bloggs', 'team': 'it', 'title': 'Frontend Developer'}, {'@id': 'Employee/004', '@type': 'Employee', 'address': {'@id': 'Address/6665e689224d412aa3a882fcfd287676', '@type': 'Address', 'postcode': 'SK5 6SY', 'street': 'Ansdell Road', 'street_num': 2, 'town': ' Stockport'}, 'contact_number': '(0161) 532 7302', 'name': 'Fabian Dalby', 'team': 'it', 'title': 'Web Service Manager'}, {'@id': 'Employee/005', '@type': 'Employee', 'address': {'@id': 'Address/358ac353adbf494f97100330b504e818', '@type': 'Address', 'postcode': 'IV27 2TG', 'street': 'Shore Street', 'street_num': 84, 'town': 'Stoer'}, 'contact_number': '070 7796 8035', 'manager': 'Employee/004', 'name': 'Ethan Abbott', 'team': 'it', 'title': 'Backend Developer'}]
 ```
 
-IT's a bit hard to see so we are going to export it to [a CSV](exported_it_team.csv):
+It's a bit hard to see so we are going to export it to [a CSV](exported_it_team.csv):
 
 `$ terminusdb alldocs --type Employee -q team=it -e --filename exported_it_team.csv`
 
@@ -78,13 +78,17 @@ team_it_avg = team_it["name"].apply(len).sum() / len(team_it)
 team_marketing_avg = team_it["name"].apply(len).sum() / len(team_marketing)
 ```
 
-Print out the results. I won't spoil the results for you, you have to find it out yourself :-)
+Print out the results.
 
 ```python
 print(f"Average name length of IT team is {team_it_avg}")
 print(f"Average name length of Marketing team is {team_marketing_avg}")
 ```
 
+I won't spoil the results for you, you have to find it out yourself :-)
+
+`$ python query_data.py`
+
 ---
 
 [Move on to Lesson 6 - Version control: time travel, branching and rebase](lesson_6.md)

getting_started/lesson_6.md

@@ -0,0 +1,218 @@
+# Lesson 6 - Version control: time travel, branching and rebase
+
+In this lesson about version control, we will be doing some git like operation that can let us collaborate and time travel.
+
+## Branch, creating a copy and jump between versions
+
+Let's follow the Awesome Startup again. Now they are super busy and decided to hire a few contractors to help out in the current project which will last for a few months. They would like to get the contractors details into the database, so they have to make a branch and ask the contractors to "fill in the details" in the branched database.
+
+Making a branch is like making a copy of the database. The good thing about this operation is that, if the contractors has does something wrong and accidentally modify the data that they should not be modifying, the changes will only be remained in the branched database. It gives the managers chances to review the changes before adopting the change in the main database.
+
+To make a branch, we can use the `terminusdb branch` or `terminusdb checkout -b` command. The difference is that `terminusdb branch` will create a new branch WITHOUT going (checkout) to that branch, while `terminusdb checkout` is used to go to another branch but with option `-b` you will create that new branch before going there.
+
+Before we create the branch, let see what we have for now:
+
+```
+$ terminusdb branch
+main
+```
+
+We only have the `main` branch. The `main` branch is the default branch that is created when you created a new database. Let's create the new barnch:
+
+```
+$ terminusdb branch contractors
+Branch 'contractors' created. Remain on 'main' branch.
+```
+
+We have created the `contractors` branch. Let's verify:
+
+```
+$ terminusdb branch            
+main
+contractors
+```
+
+Now the contractors can add their details with the script [add_contractors.py](add_contractors.py). We add the two contractors in similar manner as adding Ethan in [lesson 4](lesson_4.md) but notice one thing:
+
+```python
+client.connect(db="getting_started", branch="contractors")
+```
+
+When we connect to the database, we have to specify the branch to be `contractors`.
+
+Now run the script:
+
+`$ python add_contractors.py`
+
+To verify we did things right, let's see if there is any changes in the current `main` branch, you can see all the logs with:
+
+```
+$ terminusdb log     
+========
+Connecting to 'getting_started' at 'http://127.0.0.1:6363/'
+on branch 'main'
+with team 'admin'
+========
+
+commit 8o4vkomwryjogg37u3abojflpzrt0r4
+Author: admin
+Date: 2021-10-15 11:48:32
+
+    Adding Ethan (inserts)
+
+commit 680q7y1wxouy9ltni344s821jvm7zn2
+Author: admin
+Date: 2021-10-15 11:48:32
+
+    Update Destiny (repleces)
+
+commit 8ebr9nm9pwgd05mlxv28g85kulrq00r
+Author: admin
+Date: 2021-10-15 11:48:31
+
+    Adding 4 Employees
+
+commit thb4axo7pi08946jhuxo68rry42vdzd
+Author: admin
+Date: 2021-10-15 11:48:31
+
+    Import Employees from CSV (inserts)
+
+commit l5a3jolxydc39khktgljppqi3a7ed3b
+Author: admin
+Date: 2021-10-15 11:48:29
+
+    Schema updated by Python client.
+
+```
+
+So the last time we make changes is adding Ethan, the contractors are not added here.
+
+Now let's go to the `contractors` branch:
+
+```
+$ terminusdb checkout contractors
+Checked out 'contractors' branch.
+```
+
+And check the log again:
+
+```
+$ terminusdb log           
+========
+Connecting to 'getting_started' at 'http://127.0.0.1:6363/'
+on branch 'contractors'
+with team 'admin'
+========
+
+commit kb4nilq4qt9b2va4l0mekv19ov8wey1
+Author: admin
+Date: 2021-10-15 11:54:21
+
+    Adding contractors (inserts)
+
+...
+
+```
+
+We have a new entry for the log.
+
+## Rebase, what is it about?
+
+After the `contractors` branch is created and "filled in". Our managers approve the change. Now, we would like to incorporate the changes back to the main branch. For those of you who are familiar with the git workflow will know that we need to perform a merge from the `contractors` branch to the `main` branch. But we are going to do something a bit difference here, using rebase instead of merge.
+
+Rebase means that we take the changes we made since the branching and will continue from another branch. For example, if we rebase `main` from `contractors` we will continue from what `contractors` is now, i.e. after adding the contractors. This means we have incorporate the change in `contractors` into `main`. For more information about rebase, see the [documentation with git](https://git-scm.com/docs/git-rebase).
+
+To do it, let's go back to `main` and rebase from `contractors`:
+
+```
+$ terminusdb checkout main
+Checked out 'main' branch.
+$ terminusdb rebase contractors
+Rebased contractors branch.
+```
+
+Now when we do `terminusdb log` we see that we have the `Adding contractors` commit in it.
+
+```
+$ terminusdb log
+========
+Connecting to 'getting_started' at 'http://127.0.0.1:6363/'
+on branch 'main'
+with team 'admin'
+========
+
+commit kb4nilq4qt9b2va4l0mekv19ov8wey1
+Author: admin
+Date: 2021-10-15 11:54:21
+
+    Adding contractors (inserts)
+
+...
+
+```
+
+## Reset, time traveling machine
+
+Time fries, now the project is done and the contractors has done their jobs and left the company. We have to time travel to the state of the company before the project.
+
+Let's verify our log again:
+
+```
+$ terminusdb log                 
+========
+Connecting to 'getting_started' at 'http://127.0.0.1:6363/'
+on branch 'main'
+with team 'admin'
+========
+
+commit kb4nilq4qt9b2va4l0mekv19ov8wey1
+Author: admin
+Date: 2021-10-15 11:54:21
+
+    Adding contractors (inserts)
+
+commit 8o4vkomwryjogg37u3abojflpzrt0r4
+Author: admin
+Date: 2021-10-15 11:48:32
+
+    Adding Ethan (inserts)
+
+...
+
+```
+
+We would like to keep the commits up to the `Adding Ethan` one, take note of the commit id of that commit. Mine is `8o4vkomwryjogg37u3abojflpzrt0r4`, yours will be different.
+
+To reset, we use the `terminusdb reset` command:
+
+```
+$ terminusdb reset 8o4vkomwryjogg37u3abojflpzrt0r4
+Hard reset to commit 8o4vkomwryjogg37u3abojflpzrt0r4
+```
+
+Notice that it is a hard reset, meaning that the changes after the commit `Adding Ethan` is gone forever! If you are not sure or just want to temporary reset to a previous time, make sure you use `--soft` option. Now let's have a look at the log again:
+
+```
+$ terminusdb log
+========
+Connecting to 'getting_started' at 'http://127.0.0.1:6363/'
+on branch 'main'
+with team 'admin'
+========
+
+commit 8o4vkomwryjogg37u3abojflpzrt0r4
+Author: admin
+Date: 2021-10-15 11:48:32
+
+    Adding Ethan (inserts)
+
+...
+
+```
+
+We are back to where we were again.
+
+---
+
+[Check out other tutorials](README.md)

getting_started/schema.py

@@ -44,8 +44,13 @@ class Employee(DocumentTemplate):
     contact_number: str
     manager: Optional["Employee"]
     name: str
-    title: str
     team: "Team"
+    title: str
+
+
+class Team(EnumTemplate):
+    marketing = ()
+    it = ()
 
 
 class EmployeesFromCSV(DocumentTemplate):
@@ -54,8 +59,3 @@ class EmployeesFromCSV(DocumentTemplate):
     name: Optional[str]
     team: Optional[str]
     title: Optional[str]
-
-
-class Team(EnumTemplate):
-    marketing = ()
-    it = ()

getting_started/update_data.py

@@ -21,7 +21,7 @@
 destiny.address.street_num = 73
 destiny.address.town = "Newbigging"
 
-client.update_document(destiny)
+client.update_document(destiny, commit_msg="Update Destiny")
 
 # Linking a new document to an old document
 
@@ -46,4 +46,4 @@
     manager=ethan_manager,
 )
 
-client.update_document(ethan)
+client.update_document(ethan, commit_msg="Adding Ethan")