Skip to content

Commit 9b9fdd1

Browse files
Get started refinements (#966)
## Goal We incorporate reviews, edits, and changes mostly from @farost and @sam-butcher comments that improve the get-started and driver core-concepts sections' usability and readability.
1 parent 793c171 commit 9b9fdd1

File tree

26 files changed

+175
-165
lines changed

26 files changed

+175
-165
lines changed

home/modules/ROOT/pages/install-tools.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ all within a unified environment.
168168
169169
[cols-2]
170170
--
171-
.https://studio.typedb.com[Open TypeDB Studio]
171+
.https://studio.typedb.com[Open TypeDB Studio,window=_blank]
172172
[.clickable]
173173
****
174174
Launch TypeDB Studio directly from your web browser.

manual/modules/ROOT/pages/tools/studio.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ all within a unified environment.
1616

1717
[cols-2]
1818
--
19-
.https://studio.typedb.com[Open TypeDB Studio]
19+
.https://studio.typedb.com[Open TypeDB Studio,window=_blank]
2020
[.clickable]
2121
****
2222
Launch TypeDB Studio directly from your web browser.

new_core_concepts/modules/ROOT/pages/drivers/overview.adoc

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
== What are TypeDB drivers?
88

9-
TypeDB drivers are client libraries that enable applications to communicate with TypeDB servers. They provide a programming language-specific interface for all database operations, from connection management to query execution.
9+
TypeDB drivers are client libraries that enable applications to communicate with TypeDB servers. They provide a programming language-specific interface for all server operations, from connection management to query execution.
1010

1111
Key responsibilities of a TypeDB driver include:
1212

@@ -17,6 +17,8 @@ Key responsibilities of a TypeDB driver include:
1717
* **Error handling**: Converting server errors into language-specific exceptions
1818
* **Resource management**: Properly managing network resources and memory
1919

20+
They also allow you to manage databases and users.
21+
2022
== Communication endpoints
2123

2224
TypeDB servers expose two different endpoints for client communication:
@@ -63,8 +65,11 @@ TypeDB Server
6365

6466
TypeDB's gRPC drivers are implemented as FFI (Foreign Function Interface) wrappers around a shared Rust driver core, enabling the core logic, validation, and error handling to be implemented once and exposed into each language with a thin wrapper.
6567

66-
This means that your driver may be platform (eg. OS and CPU architecture) specific, and make your application non-portable.
67-
However, this is typically not a problem - Rust compiles per-platform or is distributed as source, Python applications are usually distributed as source, and the Java driver is specifically built to support major platforms to allow shipping built Java applications.
68+
This means that your driver may be platform (eg. OS and CPU architecture) specific, and make your application non-portable. However, this is typically not a problem:
69+
70+
- Rust compiles per-platform or is distributed as source.
71+
- Python applications are usually distributed as source.
72+
- The Java driver is specifically built to support major platforms to allow shipping built Java applications.
6873

6974
== Basic driver workflow
7075

new_core_concepts/modules/ROOT/pages/drivers/transactions.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ After opening a driver with the correct configuration and credentials, you can o
1212

1313
TypeDB provides three distinct transaction types, each with specific capabilities:
1414

15-
[cols="3,2"]
15+
[cols="1,3"]
1616
|===
1717
|Type |Capabilities
1818

@@ -39,7 +39,7 @@ a|* Execute read queries +
3939

4040
=== ACID guarantees
4141

42-
TypeDB transactions provide ACID guarantees up to **snapshot isolation**. For more details, see the server xref::{page-version}@new_core_concepts/typedb/transactions.adoc[Transaction] documentation.
42+
TypeDB transactions provide ACID guarantees up to **snapshot isolation**. For more details, see the server xref:{page-version}@new_core_concepts::typedb/transactions.adoc[Transaction] documentation.
4343

4444
== Transaction lifecycle
4545

new_home/modules/ROOT/pages/get_started/data.adoc

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,14 @@ In the previous sections we've:
1414
.. Created a database called `get_started`.
1515
.. Defined the social network schema:
1616
+
17+
[%collapsible]
18+
====
1719
[,typeql]
1820
----
1921
#!test[schema]
2022
include::{page-version}@new_home::page$get_started/schema.adoc[tag=full_define]
2123
----
24+
====
2225

2326
== Overview
2427

@@ -174,10 +177,7 @@ Studio::
174177
In order to insert a friendship, we need to refer to users that will play the role of friends in the friendship.
175178
That's where variables come into play!
176179
177-
[Note]
178-
-----
179180
Recall that each friendship takes exactly two friends as specified in the schema; feel free to experiment though, and see what error messages TypeDB will give you when trying to insert triple friendships.
180-
-----
181181
182182
[,typeql]
183183
----
@@ -198,10 +198,7 @@ Console::
198198
In order to insert a friendship, we need to refer to users that will play the role of friends in the friendship.
199199
That's where variables come into play!
200200
201-
[Note]
202-
-----
203201
Recall that each friendship takes exactly two friends as specified in the schema; feel free to experiment though, and see what error messages TypeDB will give you when trying to insert triple friendships.
204-
-----
205202
206203
Using a new `write` transaction, run:
207204

new_home/modules/ROOT/pages/get_started/overview.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ The following outline serves both as an example of the main things you'll do wit
1717
and a quick outline of the following Get Started guide - if you just want to speed through right here you can, though we recommend following the full guide!
1818

1919
. xref:{page-version}@new_home::get_started/setup.adoc[]
20-
.. Sign up & launch a free TypeDB instance on https://cloud.typedb.com[TypeDB Cloud account].
21-
.. Follow the instructions from the cluster to open https://studio.typedb.com[TypeDB Studio].
20+
.. Sign up & launch a free TypeDB instance on https://cloud.typedb.com[TypeDB Cloud account,window=_blank].
21+
.. Follow the instructions from the cluster to open https://studio.typedb.com[TypeDB Studio,window=_blank].
2222

2323
. xref:{page-version}@new_home::get_started/schema.adoc[]
2424
.. Create a database called `get_started`.

new_home/modules/ROOT/pages/get_started/query-composition.adoc

Lines changed: 72 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -13,36 +13,42 @@ In the previous sections we've:
1313
.. Created a database called `get_started`.
1414
.. Defined the social network schema:
1515
+
16+
[%collapsible]
17+
====
1618
[,typeql]
1719
----
1820
#!test[schema]
1921
include::{page-version}@new_home::page$get_started/schema.adoc[tag=full_define]
2022
----
23+
====
2124
. xref:get_started/data.adoc[Loaded some data] using a insert and match-insert queries:
22-
+
25+
26+
[%collapsible]
27+
====
2328
[,typeql]
2429
----
2530
#!test[write]
2631
include::{page-version}@new_home::page$get_started/data.adoc[tag=insert2]
2732
----
28-
+
33+
2934
[,typeql]
3035
----
3136
#!test[write]
3237
include::{page-version}@new_home::page$get_started/data.adoc[tag=insert3]
3338
----
34-
+
39+
3540
[,typeql]
3641
----
3742
#!test[write]
3843
include::{page-version}@new_home::page$get_started/data.adoc[tag=insert5]
3944
----
40-
+
45+
4146
[,typeql]
4247
----
4348
#!test[write, count=1]
4449
include::{page-version}@new_home::page$get_started/data.adoc[tag=match-insert1]
4550
----
51+
====
4652

4753
== Overview
4854

@@ -150,27 +156,28 @@ reduce $num-friends = count groupby $user, $username;
150156
# end::reduce2[]
151157
152158
tag::reduce2_result[]
153-
------------------------------
154-
$num-friends | 1
155-
$user | isa user, iid 0x1e00000000000000000004
156-
$username | isa username "echo"
157-
------------------
158-
$num-friends | 1
159-
$user | isa user, iid 0x1e00000000000000000000
160-
$username | isa username "alice"
161159
------------------
162160
$num-friends | 1
163161
$user | isa user, iid 0x1e00000000000000000005
164162
$username | isa username "fizzbuzz"
165163
------------------
164+
$num-friends | 1
165+
$user | isa user, iid 0x1e00000000000000000001
166+
$username | isa username "bob"
167+
------------------
166168
$num-friends | 2
167169
$user | isa user, iid 0x1e00000000000000000003
168170
$username | isa username "delta"
169171
------------------
170172
$num-friends | 1
171-
$user | isa user, iid 0x1e00000000000000000001
172-
$username | isa username "bob"
173+
$user | isa user, iid 0x1e00000000000000000000
174+
$username | isa username "alice"
173175
------------------
176+
$num-friends | 1
177+
$user | isa user, iid 0x1e00000000000000000004
178+
$username | isa username "echo"
179+
------------------
180+
174181
# end::reduce2_result[]
175182
----
176183
////
@@ -290,8 +297,8 @@ limit 1;
290297
# tag::pipeline1_result[]
291298
------------------
292299
$num-friends | 2
293-
$user | isa user, iid 0x1e00000000000000000006
294-
$username | isa username delta
300+
$user | isa user, iid 0x1e00000000000000000003
301+
$username | isa username "delta"
295302
------------------
296303
# end::pipeline1_result[]
297304
----
@@ -369,19 +376,19 @@ not { friendship ($user, $other-user); };
369376
370377
# tag::pipeline2_result[]
371378
---------------------
372-
$other-user | isa user, iid 0x1e00000000000000000001
379+
$other-user | isa user, iid 0x1e00000000000000000000
373380
$other-username | isa username "alice"
374-
$user | isa user, iid 0x1e00000000000000000006
381+
$user | isa user, iid 0x1e00000000000000000003
375382
$username | isa username "delta"
376383
---------------------
377-
$other-user | isa user, iid 0x1e00000000000000000002
384+
$other-user | isa user, iid 0x1e00000000000000000001
378385
$other-username | isa username "bob"
379-
$user | isa user, iid 0x1e00000000000000000006
386+
$user | isa user, iid 0x1e00000000000000000003
380387
$username | isa username "delta"
381388
---------------------
382-
$other-user | isa user, iid 0x1e00000000000000000003
389+
$other-user | isa user, iid 0x1e00000000000000000002
383390
$other-username | isa username "charlene"
384-
$user | isa user, iid 0x1e00000000000000000006
391+
$user | isa user, iid 0x1e00000000000000000003
385392
$username | isa username "delta"
386393
---------------------
387394
# end::pipeline2_result[]
@@ -564,37 +571,37 @@ Console::
564571
# tag::function_pipeline1[]
565572
match
566573
let $most-popular-user, $most-popular-username = most_popular_user();
567-
$other-user isa user, has username $username;
574+
$other-user isa user, has username $other-username;
568575
not { $most-popular-user is $other-user; };
569576
friendship ($other-user, $most-popular-user);
570577
# end::function_pipeline1[]
571578
572579
# tag::function_pipeline1_result[]
573580
----------------------------
574-
$most-popular-user | isa user, iid 0x1e00000000000000000006
575-
$most-popular-username | isa username "deltaonenine"
576-
$other-user | isa user, iid 0x1e00000000000000000007
577-
$username | isa username "ecclestone"
581+
$most-popular-user | isa user, iid 0x1e00000000000000000003
582+
$most-popular-username | isa username "delta"
583+
$other-user | isa user, iid 0x1e00000000000000000004
584+
$other-username | isa username "echo"
585+
----------------------------
586+
$most-popular-user | isa user, iid 0x1e00000000000000000003
587+
$most-popular-username | isa username "delta"
588+
$other-user | isa user, iid 0x1e00000000000000000005
589+
$other-username | isa username "fizzbuzz"
578590
----------------------------
579-
$most-popular-user | isa user, iid 0x1e00000000000000000006
580-
$most-popular-username | isa username "deltaonenine"
581-
$other-user | isa user, iid 0x1e00000000000000000008
582-
$username | isa username "fizzbuzz"
591+
$most-popular-user | isa user, iid 0x1e00000000000000000003
592+
$most-popular-username | isa username "delta"
593+
$other-user | isa user, iid 0x1e00000000000000000000
594+
$other-username | isa username "alice"
583595
----------------------------
584-
$most-popular-user | isa user, iid 0x1e00000000000000000006
585-
$most-popular-username | isa username "deltaonenine"
596+
$most-popular-user | isa user, iid 0x1e00000000000000000003
597+
$most-popular-username | isa username "delta"
586598
$other-user | isa user, iid 0x1e00000000000000000001
587-
$username | isa username "alice1925"
599+
$other-username | isa username "bob"
588600
----------------------------
589-
$most-popular-user | isa user, iid 0x1e00000000000000000006
590-
$most-popular-username | isa username "deltaonenine"
601+
$most-popular-user | isa user, iid 0x1e00000000000000000003
602+
$most-popular-username | isa username "delta"
591603
$other-user | isa user, iid 0x1e00000000000000000002
592-
$username | isa username "bob78"
593-
----------------------------
594-
$most-popular-user | isa user, iid 0x1e00000000000000000006
595-
$most-popular-username | isa username "deltaonenine"
596-
$other-user | isa user, iid 0x1e00000000000000000003
597-
$username | isa username "candice001"
604+
$other-username | isa username "charlene"
598605
----------------------------
599606
# end::function_pipeline1_result[]
600607
----
@@ -644,13 +651,11 @@ include::./query-composition.adoc[tag=fetch1]
644651
----
645652
646653
This query now returns a sequence of JSON documents:
647-
[source]
654+
[source, json]
648655
----
649-
include::./query-composition.adoc[tag=fetch_1_result]
656+
include::./query-composition.adoc[tag=fetch1_result]
650657
----
651658
652-
The fetch clause lets you lay out the exact JSON document you need for your application, making it easy to retrieve additional data such as optional attributes or answers from subqueries.
653-
654659
--
655660
Console::
656661
+
@@ -679,38 +684,38 @@ fetch {
679684
};
680685
# end::fetch1[]
681686
682-
# tag::fetch_1_result[]
687+
# tag::fetch1_result[]
683688
{
689+
"username": "alice",
684690
"friends": [
685691
{
686-
"friend": "bob78"
692+
"friend": "bob"
687693
},
688694
{
689-
"friend": "deltaonenine"
695+
"friend": "delta"
690696
}
691-
],
692-
"username": "alice1925"
697+
]
693698
}
694699
{
700+
"username": "bob",
695701
"friends": [
696702
{
697-
"friend": "alice1925"
703+
"friend": "alice"
698704
},
699705
{
700-
"friend": "deltaonenine"
706+
"friend": "delta"
701707
}
702-
],
703-
"username": "bob78"
708+
]
704709
}
705710
{
706-
"username": "candice001",
711+
"username": "charlene",
707712
"friends": [
708713
{
709-
"friend": "deltaonenine"
714+
"friend": "delta"
710715
}
711716
]
712717
}
713-
#end::fetch_1_result[]
718+
#end::fetch1_result[]
714719
----
715720
////
716721
[,typeql]
@@ -719,11 +724,19 @@ fetch {
719724
include::./query-composition.adoc[tag=fetch1]
720725
----
721726
722-
The fetch clause lets you lay out the exact JSON document you need for your application, making it easy to retrieve additional data such as optional attributes or answers from subqueries.
727+
This query now returns a sequence of JSON documents:
728+
729+
[source, json]
730+
----
731+
include::./query-composition.adoc[tag=fetch1_result]
732+
----
723733
724734
--
725735
====
726736

737+
The fetch clause lets you lay out the exact JSON document you need for your application, making it easy to retrieve additional data such as optional attributes or answers from subqueries.
738+
739+
727740
== What next?
728741
There is much more to explore in the world of TypeDB, including building custom query logic using disjunctions and negations, the deep exploration of data connection using functional recursion, and more.
729742

0 commit comments

Comments
 (0)