Permalink
Browse files

fix some spelling/grammar errors in the docs

  • Loading branch information...
1 parent 9448962 commit 886a14d00bf45785e2345fb29c340911698f883c @bdrupieski bdrupieski committed Nov 28, 2015
@@ -69,7 +69,7 @@ Quick Introduction
==================
.. note::
- The rest of this chapter is based on the `Hello Slick template`_. The prefered
+ The rest of this chapter is based on the `Hello Slick template`_. The preferred
way of reading this introduction is in Activator_, where you can edit and run the code
directly while reading the tutorial.
@@ -82,7 +82,7 @@ from Slick's ``H2Profile``. A profile's ``api`` object contains all commonly
needed imports from the profile and other parts of Slick such as
:doc:`database handling <database>`.
-Slick's API is fully asynchronous and runs database call in a separate thread pool. For running
+Slick's API is fully asynchronous and runs database calls in a separate thread pool. For running
user code in composition of ``DBIOAction`` and ``Future`` values, we import the global
``ExecutionContext``. When using Slick as part of a larger application (e.g. with Play_ or
Akka_) the framework may provide a better alternative to this default ``ExecutionContext``.
@@ -183,7 +183,7 @@ the ``map`` method or a *for comprehension*:
.. includecode:: code/FirstExample.scala#projection
-The output will be the same: For each row of the table, all columns get
+The output will be the same: for each row of the table, all columns get
converted to strings and concatenated into one tab-separated string. The
difference is that all of this now happens inside the database engine, and
only the resulting concatenated string is shipped to the client. Note that we
@@ -11,7 +11,7 @@ What is Slick?
Slick ("Scala Language-Integrated Connection Kit") is `Typesafe <http://www.typesafe.com>`_'s
Functional Relational Mapping (FRM) library for Scala that makes it easy to work with relational
databases. It allows you to work with stored data almost as if you were using Scala collections
-while at the same time giving you full control over when a database access happens and which data
+while at the same time giving you full control over when database access happens and which data
is transferred. You can also use SQL directly. Execution of database actions is done
asynchronously, making Slick a perfect fit for your reactive applications based on Play_ and Akka_.
@@ -53,7 +53,7 @@ Some of the key benefits of Slick's FRM approach for functional programming incl
* Efficiency with Pre-Optimization
-FRM is more efficient way to connect; unlike ORM it has the ability to pre-optimize its
+FRM is a more efficient way to connect; unlike ORM it has the ability to pre-optimize its
communication with the database - and with FRM you get this out of the box. The road to making an
app faster is much shorter with FRM than ORM.
@@ -123,7 +123,7 @@ The Scala-based query API for Slick allows you to write database queries like qu
Scala collections. Please see :doc:`gettingstarted` for an introduction. Most of this
user manual focuses on this API.
-If you want to write your own SQL statements and still execute them asynchronously like a
+If you want to write your own SQL statements and still execute them asynchronously like
normal Slick queries, you can use the :doc:`Plain SQL<sql>` API:
.. includecode:: code/GettingStartedOverview.scala#what-is-slick-micro-example-plainsql
@@ -7,7 +7,7 @@ Slick is not an object-relational mapper (ORM) like Hibernate or other JPA_-base
A good term to describe Slick is functional-relational mapper. Slick allows working with relational data much like with immutable collections and focuses on flexible query composition and strongly controlled side-effects. ORMs usually expose mutable object-graphs, use side-effects like read- and write-caches and hard-code support for anticipated use-cases like inheritance or relationships via association tables. Slick focuses on getting the best out of accessing a relational data store. ORMs focus on persisting an object-graph.
-ORMs are a natural approach when using databases from object-oriented languages. They try to allow working with persisted object-graphs partly as if they were completely in memory. Objects can be modified, associations can be changed and the object graph can be traversed. In practice this is not exactly easy to achieve due to the so called object-relational impedance mismatch. It makes ORMs hard to implement and often complicated to use for more than simple cases and if performance matters. Slick in contrast does not expose an object-graph. It is inspired by SQL and the relational model and mostly just maps their concepts to the most closely corresponding, type-safe Scala features. Database queries are expressed using a restricted, immutable, purely-functional subset of Scala much like collections. Slick also offer :doc:`first-class SQL support <sql>` as an alternative.
+ORMs are a natural approach when using databases from object-oriented languages. They try to allow working with persisted object-graphs partly as if they were completely in memory. Objects can be modified, associations can be changed and the object graph can be traversed. In practice this is not exactly easy to achieve due to the so called object-relational impedance mismatch. It makes ORMs hard to implement and often complicated to use for more than simple cases and if performance matters. Slick in contrast does not expose an object-graph. It is inspired by SQL and the relational model and mostly just maps their concepts to the most closely corresponding, type-safe Scala features. Database queries are expressed using a restricted, immutable, purely-functional subset of Scala much like collections. Slick also offers :doc:`first-class SQL support <sql>` as an alternative.
In practice, ORMs often suffer from conceptual problems of what they try to achieve, from mere problems of the implementations and from mis-use, because of their complexity. In the following we look at many features of ORMs and what you would use with Slick instead. We'll first look at how to work with the object graph. We then look at a series of particular features and use cases and how to handle them with Slick.
@@ -53,7 +53,7 @@ Slick works differently. To do the same in Slick you would write the following.
As we can see it looks very much like collection operations but the values we get are of type ``Query``. They do not
store results, only a plan of the operations that are needed to create a SQL query that produces the results when
-needed. No database round trips happen at all in our example. To actually fetch results, we can have to compile the
+needed. No database round trips happen at all in our example. To actually fetch results, we have to compile the
query to a :doc:`database Action <database>` with ``.result`` and then ``run`` it on the Database.
.. includecode:: code/OrmToSlick.scala#slickExecution
@@ -114,7 +114,7 @@ As already mentioned, we are working with placeholder values, merely describing
It is important to note that Scala allows to be very type-safe here. E.g. Slick supports a method ``.substring`` for ``Rep[String]`` but not for ``Rep[Int]``. This is impossible in Java and Java APIs like Criteria Queries, but possible in Scala using type-parameter based method extensions via implicits. This allows tools like the Scala compiler and IDEs to understand the code much more precisely and offer better checking and support.
-A nice property of a Slick-like query language is, that it can be used with Scala's comprehension syntax, which is just Scala-builtin syntactic sugar for collections operations. The above example can alternatively be written as
+A nice property of a Slick-like query language is that it can be used with Scala's comprehension syntax, which is just Scala-builtin syntactic sugar for collections operations. The above example can alternatively be written as
.. includecode:: code/OrmToSlick.scala#slickForComprehension
@@ -124,7 +124,7 @@ Scala's comprehension syntax looks much like SQL or ORM query languages. It howe
Despite the syntactic limitations, the comprehension syntax is convenient when dealing with multiple inner joins.
-It is important to note that the problems of method-based query apis like Criteria Queries described above are not a conceptual limitation of ORM query languages but merely an artifact of many ORMs being Java frameworks. In principle, a Scala ORMs could offer a query language just like Slick's and they should. Comfortably compositional queries allow for a high degree of code re-use. They seem to be Slick's favorite feature for many developers.
+It is important to note that the problems of method-based query APIs like Criteria Queries described above are not a conceptual limitation of ORM query languages but merely an artifact of many ORMs being Java frameworks. In principle, Scala ORMs could offer a query language just like Slick's and they should. Comfortably compositional queries allow for a high degree of code re-use. They seem to be Slick's favorite feature for many developers.
Macro-based embeddings
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -172,13 +172,13 @@ For inserts, we insert into the query, that resembles the whole table and can se
Relationships
--------------------
-ORMs usually provide built-in, hard-coded support for 1-to-many and many-to-many relationships. They can be set up centrally in the configuration. In SQL on the other hand you would specify them using joins in every single query. You have a lot of flexibility what you join and how. With Slick you get the best of both worlds. Slick queries are as flexible as SQL, but also compositional. You can store fragements like join conditions in central places and use language-level abstraction. Relationships of any sort are just one thing you can naturally abstract over like in any Scala code. There is no need for Slick to hard-code support for certain use cases. You can easily implement arbitrary use cases yourself, e.g. the common 1-n or n-n relationships or even relationships spanning over multiple tables, relationships with additional discriminators, polymorphic relationships, etc.
+ORMs usually provide built-in, hard-coded support for 1-to-many and many-to-many relationships. They can be set up centrally in the configuration. In SQL on the other hand you would specify them using joins in every single query. You have a lot of flexibility what you join and how. With Slick you get the best of both worlds. Slick queries are as flexible as SQL, but also compositional. You can store fragments like join conditions in central places and use language-level abstraction. Relationships of any sort are just one thing you can naturally abstract over like in any Scala code. There is no need for Slick to hard-code support for certain use cases. You can easily implement arbitrary use cases yourself, e.g. the common 1-n or n-n relationships or even relationships spanning over multiple tables, relationships with additional discriminators, polymorphic relationships, etc.
Here is an example for person and addresses.
.. includecode:: code/OrmToSlick.scala#slickRelationships
-A common question for new Slick users is how they can follow a relationships on a result. In an ORM you could do something like this:
+A common question for new Slick users is how they can follow a relationship on a result. In an ORM you could do something like this:
.. includecode:: code/OrmToSlick.scala#relationshipNavigation
@@ -192,19 +192,19 @@ A variant of this question Slick new comers often ask is how they can do somethi
.. includecode:: code/OrmToSlick.scala#relationshipNavigation2
-The problem is that this hard-codes that a Person requires an Address. It can not be loaded without it. This does't fit to Slick's philosophy of giving you fine-grained control over what you load exactly. With Slick it is advised to map one table to a tuple or case class without them having object references to related objects. Instead you can write a function that joins two tables and returns them as a tuple or association case class instance, providing an association externally, not strongly tied one of the classes.
+The problem is that this hard-codes that a Person requires an Address. It cannot be loaded without it. This doesn't fit to Slick's philosophy of giving you fine-grained control over what you load exactly. With Slick it is advised to map one table to a tuple or case class without them having object references to related objects. Instead you can write a function that joins two tables and returns them as a tuple or association case class instance, providing an association externally, not strongly tied one of the classes.
.. includecode:: code/OrmToSlick.scala#associationTuple
An alternative approach is giving your classes Option-typed members referring to related objects, where None means that the related objects have not been loaded yet. However this is less type-safe then using a tuple or case class, because it cannot be statically checked, if the related object is loaded.
Modifying relationships
________________________
-When manipulating relationships with ORMs you usually work on mutable collections of associated objects and inserts or remove related objects. Changes are written to the database immediately or recorded in a write cache and commited later. To avoid stateful caches and mutability, Slick handles relationship manipulations just like SQL - using foreign keys. Changing relationships means updating foreign key fields to new ids, just like updating any other field. As a bonus this allows establishing and removing associations with objects that have not been loaded into memory. Having their ids is sufficient.
+When manipulating relationships with ORMs you usually work on mutable collections of associated objects and inserts or remove related objects. Changes are written to the database immediately or recorded in a write cache and committed later. To avoid stateful caches and mutability, Slick handles relationship manipulations just like SQL - using foreign keys. Changing relationships means updating foreign key fields to new ids, just like updating any other field. As a bonus this allows establishing and removing associations with objects that have not been loaded into memory. Having their ids is sufficient.
Inheritance
-----------------
-Slick does not persist arbitrary object-graphs. It rather exposes the relational data model nicely integrated into Scala. As the relational schema doesn't contain inheritance so doesn't Slick. This can be unfamiliar at first. Usually inheritance can be simply replaced by relationalships thinking along the lines of roles. Instead of foo is a bar think foo has role bar. As Slick allows query composition and abstraction, inheritance-like query-snippets can be easily implemented and put into functions for re-use. Slick doesn't provide any out of the box but allows you to flexibly come up with the ones that match your problem and use them in your queries.
+Slick does not persist arbitrary object-graphs. It rather exposes the relational data model nicely integrated into Scala. As the relational schema doesn't contain inheritance so doesn't Slick. This can be unfamiliar at first. Usually inheritance can be simply replaced by relationships thinking along the lines of roles. Instead of foo is a bar think foo has role bar. As Slick allows query composition and abstraction, inheritance-like query-snippets can be easily implemented and put into functions for re-use. Slick doesn't provide any out of the box but allows you to flexibly come up with the ones that match your problem and use them in your queries.
Code-generation
-----------------
Oops, something went wrong.

0 comments on commit 886a14d

Please sign in to comment.