Skip to content
This repository was archived by the owner on Dec 24, 2022. It is now read-only.

Commit bbd7c1e

Browse files
mythzmythz
committed
Move API Usage closer to top
1 parent 5fed002 commit bbd7c1e

File tree

1 file changed

+102
-107
lines changed

1 file changed

+102
-107
lines changed

‎README.md

Lines changed: 102 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,101 @@ db.Delete(table: "Person", where: "Age = {0}".Params(27));
314314

315315
**DELETE FROM "Person" WHERE Age = 27**
316316

317+
# API Overview
318+
319+
The API is minimal, providing basic shortcuts for the primitive SQL statements:
320+
321+
[![OrmLite API](http://mono.servicestack.net/files/ormlite-api.png)](http://www.servicestack.net/files/ormlite-api.png)
322+
323+
### Notes
324+
325+
Extension methods hang off the implementation agnostic ADO.NET `IDbConnection`.
326+
327+
`CreateTable<T>` and `DropTable<T>` create and drop tables based on a classes type definition (only public properties used).
328+
329+
By default Selection methods use parameterized SQL whilst any selection methods ending with **Fmt** allow you to construct Sql using C# `string.Format()` syntax.
330+
331+
If your SQL doesn't start with a **SELECT** statement, it is assumed a WHERE clause is being provided, e.g:
332+
333+
```csharp
334+
var tracks = db.SelectFmt<Track>("Artist = {0} AND Album = {1}", "Nirvana", "Heart Shaped Box");
335+
```
336+
337+
The same results could also be fetched with:
338+
339+
```csharp
340+
var tracks = db.SelectFmt<Track>("select * from track WHERE Artist={0} AND Album={1}", "Nirvana", "Heart Shaped Box");
341+
```
342+
343+
**Select** returns multiple records
344+
345+
```csharp
346+
List<Track> tracks = db.Select<Track>()
347+
```
348+
349+
**Single** returns a single record. Alias: `First`
350+
351+
```csharp
352+
Track track = db.SingleFmt<Track>("RefId = {0}", refId)
353+
```
354+
355+
**Dictionary** returns a Dictionary made from the first two columns. Alias: `GetDictionary`
356+
357+
```csharp
358+
Dictionary<int, string> trackIdNamesMap = db.Dictionary<int, string>("select Id, Name from Track")
359+
```
360+
361+
**Lookup** returns an `Dictionary<K, List<V>>` made from the first two columns. Alias: `GetLookup`
362+
363+
```csharp
364+
Dictionary<int, List<string>> albumTrackNames = db.Lookup<int, string>("select AlbumId, Name from Track")
365+
```
366+
367+
**List** returns a List of first column values. Alias: `GetList`
368+
369+
```csharp
370+
List<string> trackNames = db.Column<string>("select Name from Track")
371+
```
372+
373+
**HashSet** returns a HashSet of distinct first column values. Alias: `GetHashSet`
374+
375+
```csharp
376+
HashSet<string> uniqueTrackNames = db.ColumnDistinct<string>("select Name from Track")
377+
```
378+
379+
**Scalar** returns a single scalar value. Alias: `GetScalar`
380+
381+
```csharp
382+
var trackCount = db.Scalar<int>("select count(*) from Track")
383+
```
384+
385+
Anonymous types passed into **Where** are treated like an **AND** filter.
386+
387+
```csharp
388+
var track3 = db.Where<Track>(new { AlbumName = "Throwing Copper", TrackNo = 3 })
389+
```
390+
391+
**Select** statements take in parameterized SQL using properties from the supplied anonymous type (if any)
392+
393+
```csharp
394+
var track3 = db.Select<Track>("select * from Track Where AlbumName = @album and TrackNo = @trackNo",
395+
new { album = "Throwing Copper", trackNo = 3 })
396+
```
397+
398+
SingleById(s), SelectById(s), etc provide strong-typed convenience methods to fetch by a Table's **Id** primary key field.
399+
400+
```csharp
401+
var track = db.SingleById<Track>(1);
402+
var tracks = db.SelectByIds<Track>(new[]{ 1,2,3 });
403+
```
404+
405+
### Other Notes
406+
407+
- All **Insert**, **Update**, and **Delete** methods take multiple params, while `Insert`, `UpdateAll` and `DeleteAll` take IEnumerables.
408+
- `Save` and `SaveAll` will Insert if no record with **Id** exists, otherwise it Updates.
409+
- Methods containing the word **Each** return an IEnumerable<T> and are lazily loaded (i.e. non-buffered).
410+
411+
317412
# Features
318413

319414
OrmLite's goal is to provide a convenient, DRY, RDBMS-agnostic typed wrapper that retains a high affinity with SQL, exposing an intuitive API that generates predictable SQL and straight-forward mapping to clean, disconnected (DTO-friendly) POCO's. This approach makes easier to reason-about your data access as it's obvious what SQL is getting executed at what time, mitigating unexpected behavior, implicit N+1 queries and leaky data access prevalent in Heavy ORMs.
@@ -418,13 +513,13 @@ The mapping also includes a fallback for referencing fully-qualified names in th
418513
Seeing how the SqlExpression is constructed, joined and mapped, we can take a look at a more advanced example to showcase more of the new API's available:
419514

420515
```csharp
421-
List<FullCustomerInfo> rows = db.Select<FullCustomerInfo>( // Map results to FullCustomerInfo POCO
422-
db.From<Customer>() // Create typed Customer SqlExpression
423-
.LeftJoin<CustomerAddress>() // Implict left join with base table
424-
.Join<Customer, Order>((c,o) => c.Id == o.CustomerId) // Explicit join and condition
425-
.Where(c => c.Name == "Customer 1") // Implicit condition on base table
426-
.And<Order>(o => o.Cost < 2) // Explicit condition on joined Table
427-
.Or<Customer,Order>((c,o) => c.Name == o.LineItem)); // Explicit condition with joined Tables
516+
List<FullCustomerInfo> rows = db.Select<FullCustomerInfo>( // Map results to FullCustomerInfo POCO
517+
db.From<Customer>() // Create typed Customer SqlExpression
518+
.LeftJoin<CustomerAddress>() // Implict left join with base table
519+
.Join<Customer, Order>((c,o) => c.Id == o.CustomerId) // Explicit join and condition
520+
.Where(c => c.Name == "Customer 1") // Implicit condition on base table
521+
.And<Order>(o => o.Cost < 2) // Explicit condition on joined Table
522+
.Or<Customer,Order>((c,o) => c.Name == o.LineItem)); // Explicit condition with joined Tables
428523
```
429524

430525
The comments next to each line document each Type of API used. Some of the new API's introduced in this example include:
@@ -1187,106 +1282,6 @@ and [Versatile](http://mono.servicestack.net/mythz_blog/?p=314)
11871282
[JSV Format](https://github.com/ServiceStack/ServiceStack.Text/wiki/JSV-Format) which although hard to do -
11881283
is actually more compact, human and parser-friendly than JSON :)
11891284

1190-
# API Overview
1191-
1192-
The API is minimal, providing basic shortcuts for the primitive SQL statements:
1193-
1194-
[![OrmLite API](http://mono.servicestack.net/files/ormlite-api.png)](http://www.servicestack.net/files/ormlite-api.png)
1195-
1196-
Nearly all extension methods hang off the implementation agnostic `IDbCommand`.
1197-
1198-
`CreateTable<T>` and `DropTable<T>` create and drop tables based on a classes type definition (only public properties used).
1199-
1200-
For a one-time use of a connection, you can query straight of the `IDbConnectionFactory` with:
1201-
1202-
```csharp
1203-
var customers = db.Where<Customer>(new { Age = 30 });
1204-
```
1205-
1206-
The **Select** methods allow you to construct Sql using C# `string.Format()` syntax.
1207-
If your SQL doesn't start with a **SELECT** statement, it is assumed a WHERE clause is being provided, e.g:
1208-
1209-
```csharp
1210-
var tracks = db.SelectFmt<Track>("Artist = {0} AND Album = {1}", "Nirvana", "Heart Shaped Box");
1211-
```
1212-
1213-
The same results could also be fetched with:
1214-
1215-
```csharp
1216-
var tracks = db.SelectFmt<Track>("select * from track WHERE Artist={0} AND Album={1}", "Nirvana", "Heart Shaped Box");
1217-
```
1218-
1219-
**Select** returns multiple records
1220-
1221-
```csharp
1222-
List<Track> tracks = db.Select<Track>()
1223-
```
1224-
1225-
**Single** returns a single record. Alias: `First`
1226-
1227-
```csharp
1228-
Track track = db.SingleFmt<Track>("RefId = {0}", refId)
1229-
```
1230-
1231-
**Dictionary** returns a Dictionary made from the first two columns. Alias: `GetDictionary`
1232-
1233-
```csharp
1234-
Dictionary<int, string> trackIdNamesMap = db.Dictionary<int, string>("select Id, Name from Track")
1235-
```
1236-
1237-
**Lookup** returns an `Dictionary<K, List<V>>` made from the first two columns. Alias: `GetLookup`
1238-
1239-
```csharp
1240-
Dictionary<int, List<string>> albumTrackNames = db.Lookup<int, string>("select AlbumId, Name from Track")
1241-
```
1242-
1243-
**List** returns a List of first column values. Alias: `GetList`
1244-
1245-
```csharp
1246-
List<string> trackNames = db.Column<string>("select Name from Track")
1247-
```
1248-
1249-
**HashSet** returns a HashSet of distinct first column values. Alias: `GetHashSet`
1250-
1251-
```csharp
1252-
HashSet<string> uniqueTrackNames = db.ColumnDistinct<string>("select Name from Track")
1253-
```
1254-
1255-
**Scalar** returns a single scalar value. Alias: `GetScalar`
1256-
1257-
```csharp
1258-
var trackCount = db.Scalar<int>("select count(*) from Track")
1259-
```
1260-
1261-
All **Insert**, **Update**, and **Delete** methods take multiple params, while `Insert`, `UpdateAll` and `DeleteAll` take IEnumerables.
1262-
**GetLastInsertId** returns the last inserted records auto incremented primary key.
1263-
1264-
`Save` and `SaveAll` will Insert if no record with **Id** exists, otherwise it Updates.
1265-
Both take multiple items, optimized to perform a single read to check for existing records and are executed within a sinlge transaction.
1266-
1267-
Methods containing the word **Each** return an IEnumerable<T> and are lazily loaded (i.e. non-buffered).
1268-
1269-
By default Selection methods use parameterized SQL whilst any selection methods ending with **Fmt** do not.
1270-
Anonymous types passed into **Where** are treated like an **AND** filter.
1271-
1272-
```csharp
1273-
var track3 = db.Where<Track>(new { AlbumName = "Throwing Copper", TrackNo = 3 })
1274-
```
1275-
1276-
**Select** statements take in parameterized SQL using properties from the supplied anonymous type (if any)
1277-
1278-
```csharp
1279-
var track3 = db.Select<Track>("select * from Track Where AlbumName = @album and TrackNo = @trackNo",
1280-
new { album = "Throwing Copper", trackNo = 3 })
1281-
```
1282-
1283-
SingleById(s), SelectById(s), etc provide strong-typed convenience methods to fetch by a Table's **Id** primary key field.
1284-
1285-
```csharp
1286-
var track = db.SingleById<Track>(1);
1287-
var tracks = db.SelectByIds<Track>(new[]{ 1,2,3 });
1288-
```
1289-
12901285
### Ignoring DTO Properties
12911286

12921287
You may use the `[Ignore]` attribute to denote DTO properties that are not fields in the table. This will force the SQL generation to ignore that property.

0 commit comments

Comments
 (0)