(http://www.couchbase.

com/)

Introduction
CouchbaseQueryLanguage,knownasN1QLorNickel,helpsyoutofindandchangedatainCouchbaseServer.Wedesignedthe
languagetobehumanreadableandwritableitisanextensiblelanguagedesignedforadhocquerying.Thequerylanguageisa
standardsemanticyouusetobuildqueryingabilityinotherprogramminglanguages.
TheN1QLDeveloperPreview1isaprebetareleaseofthelanguage.Itprovidesasubsetoffunctionalityfromthefullquery
language.
N1QLissimilartothestandardSQLlanguageforrelationaldatabases,butitisalsoincludessomeadditionalfeatureswhichare
suitedfordocumentorienteddatabases.Thisguidedescribeskeyconceptsaboutthelanguage,providestutorialsdescribinghowto
usethelanguage,discussesadvancedoperationsyoucanperformwiththelanguage,andincludesalanguagereferencefor
languagesyntaxandlanguageelements.

GoalsofLanguage
N1QLisdesignedtobeaconcise,intuitive,expressivelanguageforbuildingcomplexqueries.Itisdesignedfordocumentoriented
databaseswhichstoreapplicationobjectsaswellastheirrelationshipsindocumentsinsteadoftables.Applicationdatacanbe
expressedasatomicvaluesorinnestedstructureswithinthedocument,suchasobjectsorarrays.Relationshipsbetween
documentscanbeexpressedasvaluesorvaluesinnestedstructures.Tofindinformationinadocumentorienteddatabase,you
needthecorrectlogicandexpressionsfornavigatingdocumentsanddocumentstructures.N1QLprovidesaclear,easyto
understandabstractionlayertoqueryandretrieveinformationinyourdocumentdatabase.

WhoUsesIt
ApplicationdevelopersanddataanalystsuseN1QLtoperformadhocquerying.Anyapplicationdeveloperwhowantstoprovide
reportsorretrievedatathatishardtofindcanuseN1QLintheirapplicationlogic.Clientlibrarydeveloperswhowanttoprovide
queryfunctionalityintheirlibrarycanuseN1QLasthestandardtobuildtheirnewAPIs.

WaystoUseIt
ThemajorusecasesforN1QLarethefollowing:

Embedcomplexqueryrequestsinyourapplicationlogic.Individualqueriescanincludepowerful
logicsuchaggregation,complexfilteringandresulttransformations.Withotherapproachesto
querying,youmighthavetoperformmultiplerequeststoachievethesameresults.
Performanalyticsandreporting.Youcanexecuteadhocqueriesfromyourapplication.For
exampleifyouwantalistofallusersinyourapplicationwhohavepurchasedaspecificitem,you
canuseN1QL.

WheretoStartLearning
Therearedifferentapproachesforlearninganewlanguage.Dependingonyourlearningstyle,youcanstartwithinformationatoneof
thelinksbelow:

Conceptsstarthereifyouwanttounderstandthetheoriesandideasbehindthelanguage.
TutorialifyouwanttotryoutsamplequerieswithN1QL.
LanguageReferencetoreadmoreaboutlanguagesyntaxandclauses.
ForthefulllanguageandsyntaxseetheN1QLlanguagereference.

Concepts
Documentorienteddatabases,suchasCouchbaseServer,usedocumentstostoreinformationaswellasrelationshipsamong
documents.Thismodelisflexibleenoughsothatyoucanchangeapplicationobjectswithouthavingtomigratethedatabaseschema
orplanforsignificantapplicationdowntime.Eventhesametypeofobjectinyourapplicationcanhaveadifferentdatastructures.For
instance,youcaninitiallyrepresentausernameasasingledocumentfield.Youcanlaterstructureauserdocumentsothatthefirst
nameandlastnameareseparatefieldsinthedocument.Youcanmakethesechangeswithoutanyapplicationdowntime,and
withouthavingtoupdatealluserdocumentsinthesystem.
Theotheradvantagetotheflexible,documentbaseddatamodelisthatitiswellsuitedtorepresentingrealworlditems.Documents
supportnestedstructures,aswellasfieldsrepresentingobjectproperties.Bothoftheseattributesenableyoutorealistically
representobjectsinyourapplication.

Tofindinformationinadocumentorienteddatabaseyouneedalanguagethatprovidesthecorrectlogicfornavigatingdocuments
anddocumentstructures.Thissectiondescribesthekeyconceptstounderstandaboutqueryingadistributed,documentoriented
database.

DataModeling
CouchbaseServerisadocumentdatabase:youstoreinformationindocumentsratherstoreitintablerows.Couchbasehasamuch
moreflexibledataformatdocumentsgenerallycontainalltheinformationaboutadataentity,includingcompounddata.Inthecase
oftraditional,relationaldatabases,youmayneedtospreaddatafromasingleobjectacrossmultipletables,inaprocessknownas
normalization.Imaginewehaveanapplicationforcontactsandtheirfamilies.Wecouldstoreeachcontactinatablerow,orwecan
choosetheequivalentdocumentbasedmodelwithanindividualdocumentpercontact:

Intraditionalrelationaldatabases,youwoulduseatabletorepresentarealworldobjectanditsrespectiveattributes.Forinstance,in
contactsdatabase,youwouldhaveatablewithcontacts,suchasid,firstname,lastnameandsoon.Asweseeintheillustration,
therelationalmodelconformstoarigidschemawithaspecifiednumberoffieldswhichrepresentaspecificpurposeinan
applicationandafixeddatatypeforeachcolumn.
Insteadofatable,wecanrepresentourobjectasoneormoredocuments.AdocumentinadocumentorienteddatabaseisaJSON
objectconsistingofanumberoffieldsthatyoudefine.Anobjectcanbeoneormoredocumentsinsteadofoneormoretablerows
attributesofeachobjectcanbefieldsinthedocument.Incomparison,arelationaldatabasehascolumnsinatablewhichholdatype
ofattribute,suchasnameorzipcode.ThereisnoschemaindocumentorienteddatabaseseveryJSONdocumentcanhaveits
ownindividualsetofkeys,althoughyoumayprobablyadoptoneormoreinformalschemasforyourdata.Unliketherelational
mode,attributeswithinadocumentdonothavetohaveapredefinedtype.Forinstanceazipcodecanbeanintegerorastringusing
thedocumentmodel.Evendocumentsbelongingtothesameclassofapplicationobjects,suchasacustomerdocumentcanhave
differentattributesthanothercustomerdocuments.Forexampleyoucanhavesomecustomershavinganextrafieldforshipping
insurance,whileothercustomerdocumentsdonothavethatfieldatall.

NestedStructuresandPaths

Intraditionalrelationaldatabases,eachrecordisrepresentedbyatablerowandattributesforarecordarerepresentedbyeach
columninatable.Inadocumentdatabase,arecordisrepresentedbyoneormoredocuments.Attributesforabusinessobjectare
representedbyfieldsinthedocument.Forexample,imagineasimpledocumentrepresentingacustomer:

{
"id":"7983345",
"name":"LiamKilpatrick",
"type":"retail"
....
}

Adocumentfieldcancontainnesteddatastructuressuchasarraysandobjectswithinanarrayorobject,youcanfurthernestdata.
Forexample,consideramorecomplexdocumentrepresentingacustomerorder:

{
"type":"customerorder",
"grand_total":1000,
"billTo":{
"street":"123foo",
"state":"CA",
},
"shipTo":{
"street":"123foo",
"state":"CA"
},
items:[
{"productId":"coffee","qty":1},
{"productId":"tea","qty":1}
]
}

ThismakesN1QLauniquequeryinglanguagecomparedtoSQL.Inordertonavigatenesteddataindocumentarraysandobjects,
N1QLsupportstheconceptofpaths.Apathusesadotnotationsyntaxandprovidesthelogicallocationofanattributewithina
document.Forexampletogetthestreetfromacustomerorder,weusethispath:

orders.shipTo.street

ThispathreferstothevalueforstreetinthebillToobject.Youuseapathwithaarraysornestedobjectsinordertogetto
attributeswithinthedatastructure.Youcanalsousearraysyntaxinyourpathtogettoinformation:

orders.items[0].productId

ThispathwillevaluatetothevaluecoffeeasthisistheproductIDforthefirstarrayelementunderitems.

Pathsenableyoutofindanddataindocumentstructureswithouthavingtogettheentiredocumentorhandleitwithinyour
application.Anydocumentdatacanberequestedandonlytherelevantinformationinthedocumentwillbereturnedtoyour
applicationthisreducesthebandwidthusedinforquerying.N1QLalsoprovidesaqueryfunctionalityknownasOVER.Thisenables
youtoflattenarrayelementswithinadocument.Whenadocumentcontainsanestedarray,youcanhaveeachmemberofthearray
joined.Thesejoinedobjectsbecomeinputtootherqueryoperations.

QueriesandResultSets
Queriesconsistofasinglecommandandzeroormoreoptionalclauses,whichcanfilter,runoperations,orperformfunctionson
data.Thequerycommandalongwithanyclausesareknownasaquerystring.Whenyouperformaquery,CouchbaseServertakes
thequerystringandproducesaresultset,whichisaJSONarraycontaininganyresultvalues.
AsofN1QLX.X,weassumethatyouperformaqueryonasingledatabucketinCouchbaseServer.ThereforewhenyouuseN1QL
1.0forqueries,itwillfindinformationinasinglebucket.Youcanhaveoneormorebucketsforasingleserverinstanceandmore
thanonebucketforanentireCouchbasecluster.ThisimpliesthattherearenoJOINoperationsfoundinotherquerylanguages
queriesarenotyetsupportedasjoinsacrossmultipledatabuckets.
Besidesacommand,eachquerycanhavemultipleoptionalparts,includingclauses,expressionsandfunctions.Expressionsare
partsofaquerywhichwillcomparevaluesagainstoneanotherorperformarithmeticcalculations,andclausesaretypicallyusedfor
thelimitingthescopeofaquery.
Whenyouperformaquery,asequenceofstepsgetsexecuted.Eachstepcorrespondstothedifferentclausesandexpressionsina
query.Theexpressionsevaluatedfirstwillproduceanintermediateresultset,whichisalsoknownasoutputobjects.Theoutput
objectsfromastepwillbecometheinputforthenextstepandproducethenextresultset.Afterallexpressionshavebeenevaluated
inaqueryyouhaveafinalresultset.

TypesofOperations
TherearedifferenttypesofexpressionsinN1QLforextracting,groupingandorderingdata.Thefollowingdescribethemajor
categoriesofoperationsandtheorderinwhichtheyarehandled:

FilterExpressionsIfyouprovideafilteringexpression,theserverappliesthistoeveryitemina
databucketandonlykeepstheitemswheretheresultistrue.
AggregateExpressionsThisexpressiongroupsallitemsinaresultsetbyevaluatingthe
aggregateexpression.Theresultsetcontainsthesegroups.
HavingExpressionsTheserverappliesthisexpressiontoallitemsinaresultsetandonlykeeps
anitemintheresultsetiftheexpressionevaluatestotrue.
OrderExpressionsAqueryorderstheitemintheresultsetbyevaluatingthisexpression.
SkipValueTheserverdiscardsthisnumberofitemsintheresultsetstartingatthefirstitemat
index0.

LanguageReference
ThisreferencesectiondescribesthesyntaxandgeneralsemanticsofN1QL.Thisincludesallavailablecommands,functions,
expressions,conditionalsandoperatorsforthelanguage.
Weusethefollowingtypographicalconventionstomarkdifferentpartsofthecommandsyntax:

Squarebrackets[]indicateoptionalparts
Separator|indicatesyouchooseonealternative
Dotsmeanthatyoucanrepeattheprecedingelementinaquery

Explain
YoucanusethiskeywordbeforeanyN1QLstatementandgetinformationabouthowthestatementoperates.

Syntax
EXPLAINstatement

Compatibility
CompatiblewithCouchbaseServer2.2

Example
PerformanyN1QLstatementprecedingbytheykeyword EXPLAIN togetJSONoutputdescribinghowthequerywouldexecute.
Forexample:

EXPLAINSELECTname,ageFROMcontactsLIMIT2

Willreturnthefollowingoutput:

{
"resultset":[
{
"root":{
"type":"limit",
"input":{
"type":"projector",
"input":{
"type":"fetch",
"input":{
"type":"scan",
"scanner":"_design//_view/_all_docs",
"bucket":"contacts"
},
"bucket":"contacts",
"projection":{
"type":"function",
"name":"VALUE",
"operands":[]
},
"as":"contacts"
},
"result":[
{
"star":true,
"expr":{
"type":"property",
"path":"default"
},
"as":""
}
]
},
"value":2
}
}
],

"info":[
{
"caller":"http:161",
"code":100,
"key":"total_rows",
"message":"1"
},
{
"caller":"http:163",
"code":101,
"key":"total_elapsed_time",
"message":"38.192789ms"
}
]
}

Select
YouusetheSELECTstatementtoextractdatafromCouchbaseServer.Theresultofthiscommandwillbeoneormoreobjects.

Syntax

SELECT[DISTINCT]resultexpr[,...]
[FROMdatasource]
[WHEREexpr]
[GROUPBYexpr[,...][HAVINGexpr]]
[ORDERBYorderingterm[,...]]
[LIMITnonnegint[OFFSETnonnegint]]
whereresultexprcanbe:
*
path.*
expr[ASidentifier]
wheredata_sourceis:
[:poolname.]bucketname[.path][[AS]identifier][OVERidentifierINpath]
wherepathis:
identifier['['nonnegint']'][.path]
whereorderingtermis:
expr[ASC|DESC]

Compatibility
CompatiblewithCouchbaseServer2.2

Description
TheSELECTstatementqueriesadatasource.ItreturnsaJSONarraycontainingzeroormoreresultobjects.Youcanseehow
SELECTbehavesasasequenceofstepsinaprocess.Eachstepintheprocessproducesresultobjectswhicharethenusedas
inputsinthenextstepuntilallstepsintheprocessarecomplete.Thepossibleelementsandoperationsinaqueryinclude:
DataSourceThisistheCouchbasedatabucketyouquery.YouprovidethisastheparameterdatasourceinaFROMclause.
Alternatelyyoucanprovidea path asdatasource.

FilteringResultsobjectsfromtheSELECTcanbefilteredbyaddingaWHEREclause.
SortingYoucanorderobjectsinaresultsetandproviderangelimitsbyusingORDERBY,LIMIT,andOFFSET.
ResultSetYougenerateasetofresultobjectswithGROUPBYorHAVINGclausesalongwitharesultexpressionlist,

resultexprlist .
DuplicateRemovalRemoveduplicateresultobjectsfromtheresultset.TodosoyouuseaDISTINCTquery.
OrderingItemsareplacedintheorderspecifiedbytheORDERBYexpressionlist
SkippingThefirstNitemsareskippedasspecifiedbytheOFFSETclause
LimitingNomorethanMitemsarereturnedasspecifiedbytheLIMITclause

Options
Thefollowingdescribesoptionalclausesyoucanuseinyourselectstatement:
DISTINCTIfyouusethe DISTINCT inyourquery,anyduplicateresultobjectswillberemovedfromtheresultset.Ifyoudo
notuse DISTINCT ,thequerywillreturnallobjectsthatmeetthequeryconditionsinaresultset.
FROMThisisanoptionalclauseforyourquery.Ifyouomitthisclause,theinputforthequeryisasingleemptyobject.The
mostcommonwaytousetheFROMclauseistoprovidea datasource whichisanameddatabucketorpath.Alternately
youcanprovidethedatabucketorpathasanaliasusingthe AS clausewith FROM. Forexample,ifyouhavecontact
documentsasfollows:

{"type":"contact",
"name":"earl",
"children":[
{"name":"xena","age":17,"gender":"f"},
{"name":"yuri","age":2,"gender":"m"}
],
"hobbies":["surfing"]
}

Youcanperformaquerywith FROM and AS togetthenameofthefirstchildlistedineachdocumentinthecontactsbucket:

SELECTchildren[0].nameASkid
FROMcontacts

Thiswillreturnaresultasfollows:

"resultset":[
{
"kid":"xena"
},
....
]

Anotherwaytousethe FROM clauseistospecifyapathwithinabucketas datasource .Thepathreferstoanarrayinthe

yourdocuments.Withthisoption,theserverevaluatesthepathforeachdocumentinthedatabucketandthevalueatthatpath
becomesaninputforthequery.Forexample,youhaveadatabucketnamed contacts whichhasdocumentsthatdescribes
eachcontactinasystem.Eachdocumenthasanarraycalled address .Togetalladdressesasinputforaquery,youuse
thisclause:

FROMcontacts.address

Thiswillgetalladdressfieldsfromallcontactsinthedatabucket.Iftheaddressfielddoesnotexistforacontact,thatcontact
willnotbepartofthequeryinput.
OVERThisclausecanoptionallyfollowa FROM clause.Thiswilliterateoverattributeswithinaspecifieddocumentarray.
Thearrayelementsbythisclausewillthenbecomeinputforfurtherqueryoperations.Forexample,imagineyouhavea
documentasfollowsandyouwanttogetallpublishedreviewersforthebeer:

{"id":"7983345",
"name":"TakayamaPaleAle",
"brewer":"HidaTakayamaBrewingCorp.",
"reviews":[
{"reviewerName":"TakeshiKitano","publication":"OutdoorJapanMagazine","date
":"3/2013"},
{"reviewerName":"MotoOhtake","publication":"JapanBeerTimes","date":"7/20
13"}
]
}

Inthiscaseyouwouldprovideastatementcontaining OVER asfollows:

SELECTreview.reviewerName,review.publication
FROMbeersASbOVERreviewINb.reviews

The OVER clauseiteratesoverthereviewsarrayandcollectsreviewerNameandpublicationfromeachelementinthe

array.Thiscollectionofobjectscanbeusedasinputforotherqueryoperations.
WHEREAnyexpressionintheclauseisevaluatedforobjectsinaresultset.IfitevaluatesasTRUEforanobject,theobject
istheobjectisincludedintheremainderofthequery.Forexample:

select*FROMplayersWHEREscore>100

GROUPBYCollectsitemsfrommultipleresultobjectsandgroupstheelementsbyoneormoreexpressions.Thisisan
aggregatequery.Forexample,ifyouhavejsondocumentsforbooksandfilmsandallfilmshaveafieldtype:moviewhile
bookshaveafieldtype:bookyoucanperformthisquery:

selecttitle,type,COUNT(*)AScountFROMcatalogGROUPBYtype

Anybooksintheresultsetwillgroupedtogetherandreturnedinanobjectwhileallfilmswillbegroupedandreturnedinanother
object.
HAVINGThisclausecanoptionallyfollowa GROUPBY clause.Itcanfilterresultobjectsfromthe GROUPBY clausewitha
givenexpression.
ORDERBYTheorderofitemsintheresultsetisdeterminedbyexpressioninthisclause.Objectsaresortedfirstbytheleft
mostexpressioninthelistofexpressions.Anyitemswiththesamesortvaluewillbesortedwiththenextexpressioninthelist.
Thisprocessrepeatsuntilallitemsaresortedandallexpressionsinthelistareevaluated.
The ORDERBY clausecanevaluateanyJSONvalue.Thismeansitcancomparevaluesofdifferenttypes.Forinstancefour
and4andwillorderbytype.Thefollowingdescribesorderbytypefromhighesttolowestprecedence:

missingvalue,knownasMISSING
nullvalue,knownasNULL
false
true
number
string
arrays,whereeachelementinthearrayiscomparedwiththecorrespondingelementinanother
array.Alongerarraywillsortafterashorterarray.
object,wherekeyvaluesfromoneobjectarecomparedtokeyvaluesfromanotherobject.
Keysareevaluatedinsortedorderforstrings.Largerobjectswillsortaftersmallerobjects.
LIMITImposesaspecificnumberofobjectsreturnedinaresultsetby SELECT .Thisclausemusthaveanonnegative
integerasupperbound.
OFFSETThisclausecanoptionallyfollowa LIMIT clause.Ifyouspecifyanoffset,thismanynumberofobjectsareomitted
fromtheresultsetbeforeenforcingaspecified LIMIT .Thisclausemustbeanonnegativeinteger.

Examples
Givencustomerorderthatappearasfollows:

{
"type":"customerorder",
"grand_total":1000,
"billToAddress":{
"street":"123foo",
"state":"CA",
"geo":{
"lat":1234,"lon":2344
}
},
"shipToAddress":{
"street":"123foo",
"state":"CA"
},
items:[
{"productId":"coffee","qty":1},
{"productId":"tea","qty":1}
]
}

FROM willreturnanyvaluesfromthe orders databucket.Forexample:

SELECT*FROMorders.billToAddress.state

Willreturnalistofallbillingstatesfromtheordersdatabucket.Sampleoutputwouldappearsasfollows:

"results":[
{
"state":"CA"
}
]

AS willreturnanyvaluesretrievedbytheselectstatementusinganaliasprovided.Forinstance:

SELECT
shipToAddress.stateASstate_abvFROMorders

Willreturnallstatesfromshiptoaddressesinanarraywhereeacharrayelementusesthealias:{state_abv:{.}}

SELECT
shipToAddress.stateASstate,
SUM(grand_total)ASgrandTotalByState
FROMorders
GROUPBYshipToAddress.state

Willgetstatesfromordersandthensumthegrand_totalsfromtheordersandlabeltheseamounts grandTotalByState in
theresultset.

WHERE willreturnresultsbasedonaconditionorexpressionprovidedinthe WHERE clauses.Forexample,withthe

customerordersdocumentswecanperformthisquery:

SELECT*FROMordersWHEREgrand_total>2000

Thisquerywillreturnaresultsetofallcustomerorderswherethe grand_total isgreaterthan2000.

ORDERBY willreturnaresultsetwhichissortedbyagivenfield.Forexample,togetallnamesinacontactdatabaseand
orderthenbyage:

SELECTshipToAddress.stateFROMordersORDERBYgrand_total.

Thiswillscanallordersandreturnallitemsinaresultsetorderedbythegrand_totalbyascendingorder,fromlowestto
highest.

LIMIT canbeusedasastandaloneclausetolimitthenumberofresults,orcanbeusedwithotherclausessuchasorderby
tolimitthenumberofsortedresultsthatappear.Forexample:

SELECTnameFROMcontactsLIMIT2

Willonlyreturntwonamesfromthecontactsdatabase.Sampleoutputwouldlooklikethis:

{
"name":"dave"
},
{
"name":"earl"
}

Ifyouusethisstatementinconjunctionwithan ORDERBY theobjectswillfirstbesortedinascendingorderandthenlimited

bythegivennumber:

SELECTnameFROMcontactsORDERBYageLIMIT3

Thisquerywillreturnthenamesofthethreeyoungestcontacts,sortedbyage.Anexampleofoutputisasfollows:

{
"name":"fred"
},
{
"name":"harry"
},
{
"name":"jane"
}

GROUPBY willreturnaresultsetwhereallordersthatmeettheconditionsaregroupedbyaparticularexpression.For
example:

SELECT
shipToAddress.stateASstate
FROMorders
WHEREgrand_total>2000
GROUPBYshipToAddress.state

Thisquerygetsallstatesfromshiptoaddressesincustomerorderswherethegrandtotalisgreaterthan2000.Theresultset
willbegroupedbystate.

HAVING canbeusedaftera GROUPBY clausetofilteritemsinagroupbyagivencondition.Thefollowingexamplebuilds

uponthe GROUPBY weusedpreviously:

SELECT
shipToAddress.stateASstate,
SUM(grand_total)ASgrandTotalByState
FROMorders
WHEREgrand_total>2
GROUPBYshipToAddress.state
HAVINGgrandTotalByState>=1000

Thiswillreturnalistofstateswherethegrandtotaloforders,groupedbystateisgreaterthanorequalto1000.Thesample
outputappearsasfollows:

[
{"state":"CA",
"grandTotalByState":10000000},
{"state":"DE",
"grandTotalByState":5000},
....
]

OVER canbeusedafterthe FROM clausetoiteratethroughallitemsinadocumentarrayandprovidetheseelementsinput

intootherqueryclauses.Forexample,togothrougheachchildinachildrenarrayincontacts:

SELECT*FROMcontactsAScontactOVERcontact.childrenASchildWHEREchild.name='aid
en'

Thisexamplewillscanallchildrenarraysincontacts,findthedocumentwherethechildsnameisaidenandreturnthe
contactsinaresultset.Anexampleresultset,givenjustonematchingcontactwouldlooklikethis:

{
"children":[
{
"age":17,
"gender":"m",
"name":"aiden"
},
{
"age":2,
"gender":"f",
"name":"amy"
}
],
"hobbies":[
"golf",
"surfing"
],
"name":"dave",
"type":"contact"
}

Heretheactualcontactisnameddaveandtheonechildinthearrayofchildrenthatmatchesis17andmale.

SeeAlso
Expressions
ComparisonTerms
Functions
ArithmeticOperators
ErrorsandResponseCodes

CreateIndex
Youusethisstatementtocreateanindexonfieldsandnestedpaths.TheindexprovidesanoptimizedaccesspathforN1QL
queries.

Syntax
CREATEINDEXindexnameON[:poolname.]bucketname(path[,...])

Compatibility
CompatiblewithCouchbaseServer2.2

Example
CREATEINDEXcontact_nameONcontacts(name)

CreatePrimaryIndex
Youusethisstatementtoensureanoptimizedprimarykeyindex.Iftheprimarykeyindexalreadyexists,thestatementwill
recognizeitandnotcreateaduplicateindex.

Syntax
CREATEPRIMARYINDEXON[:poolname.]bucketname

Compatibility
CompatiblewithCouchbaseServer2.2

Example
CREATEPRIMARYINDEXONcontacts

DropIndex
Youusethisstatementtoremoveanamedindexinthegivenbucket.

Syntax
DROPINDEX[:poolname.]bucketname.indexname

Compatibility
CompatiblewithCouchbaseServer2.2

Example
DROPINDEXcontacts.contact_name

Expressions
ThesearethedifferentsymbolsandoperatorsinN1QLyoucanusetomanipulatedocumentdataandresultsetobjects.

Syntax

[literalvalue]
[identifier]
[caseexpr]
[collectionexpr]
[logicalterm]
[comparisonterm]
[arithmeticterm]
[stringterm]
[function]
[nestedexpr]
[expr]
whereliteralvaluecanbeoneof:
[string|number|object|array|TRUE|FALSE|NULL]
whereidentifiercanbeoneof:
[unescapedidentifier|escapedidentifier]
whereunescapedidentifieris:
az|AZ|_|&[09|az|aZ|_|$]
whereescapedidentifieris:
`chars`
wherecaseexprisasfollows:
CASEWHENexprTHENexpr[,...][ELSEexpr]END
wherecollectionexprisasfollows:
ANY|ALLexprOVERidentifierINpathEND
FIRST|ARRAYexprOVERidentifierINpath[WHENexpr]END
wherenestedexprcanbeoneof:
expr.expr
expr[expr]
wherefunctionisafollows:
functionname([[DISTINCT]*|path.*|expr[,...]])

Compatibility
CompatiblewithCouchbaseServer2.2

Description
N1QLexpressionsarelikeformulasbuttheyarewritteninaquerylanguage.Theyincludeoperators,symbolsandvaluesyoucan
usetoevaluateandfilterresultobjects.

Options
literalvalue includesstandardliteralvaluesinJSON.Thisincludesstrings,numbers,objects,arrays,theboolean
TRUE/FALSEaswellasNULL.Therulesdefinedatjson.org(http://www.json.org/)applytoliteralvaluesinN1QLwithtwo
exceptions:

JSONarraysandobjectscanonlycontainnestedvalues.InN1QL,literalarraysandobjects
canalsocontainnestedexpressions.
InJSONtrue,false,andnullarecasesensitive.InN1QLtheyarecaseinsensitivetobe
consistentwithotherkeywords.
identifier isalsoknownasapath.Itcanbeanescapedorunescapedidentifier.Unescapedidentifierssupportthemost
commonidentifiersinJSONasasimplersyntax.Escapedidentifiersaresurroundedbybackticksandsupportallidentifiers
inJSON.Usingtwobacktickswithinanescapedidentifierwillcreateasinglebacktick.Thesyntaxfor identifier isas
follows:
Anidentifierisareferencetoavalueinthecurrentcontextofaquery.Forinstanceifyouhaveacontactsdatabasewitha
documentstructureasfollows:

{
"firstName":"Geremy"
"lastName":"Irving"
}

Theidentifierperson.lastNamewouldevaluatetothevalueIrving.

nestedexpr isawaytospecifyfieldsnestedinsideofotherobjects.Itcanincludethedotoperator, . ,aswellas

bracketnotation, [] toaccessitemsinanarrayorobject.Forexampleourcontactsdocumentscanhavethefollowing
documentstructure:

{
"address":{
"city":"MountainView"
},
"revisions":[2013]
}

Theexpression address.city evaluatestothevalueMountainViewandtheexpression revisions[0] evaluatesto

thevalue 2013 .

caseexpr Youcandoconditionallogicinanexpression.Ifthefirst WHEN expressionevaluatestoTRUE,theresultfor

thisexpressionisthe THEN expression.Ifthefirst WHEN evaluatestoFALSE,thenthenext WHEN clauseswillbe
evaluated.Ifno WHEN clauseevaluatesto TRUE theresultisthe ELSE expression.Ifno ELSE expressionisprovidedin
theclause,theresultisNULL.

collectionexpr Enablesyoutoevaluateexpressionsusingnestedcollections.Thedifferentformsofcollection
expressionsarespecifiedusing ANY , ALL , FIRST ,or ARRAY .Youprovideanarraytoevaluateasa path inan

OVER clause.Theserverwilliteratethrougheachelementinthearrayandassigneachiteman identifier fromthe IN

clause.The identifier isonlyusedasaidentifierwithinthecollectionexpressionandisdistinctfromidentifiersprovided
inotherclauses.

ANY Ifatleastoneiteminthearraysatisfiesthe ANY expression,thenreturn TRUE ,otherwisereturn FALSE .

ALL Ifallarrayelementssatisfythe ALL expression,returnTRUE.Otherwisereturn FALSE. Ifthearrayisempty,return
TRUE .
FIRST Returntheevaluatedexpressionusingthefirstarrayelement(thatsatisifiesthe WHEN clause,ifprovided).
ARRAY Returnsanewarrayoftheevaluatedexpressionusingeachelementofthe OVER array(thatsatisifiesthe WHEN
clause,ifprovided).

logicalterm Enablesyoutocombineotherexpressionwithbooleanlogic.Includes AND , OR ,and NOT .

comparisonterm Theseclausesenableyoutocomparetheresultsoftwoexpressions.Thisincludes = , < , > , <= ,
>= andothers.Theterms = and == arefunctionalequivalentsofequalwhichareprovidedforcompatibilitywithother
languages.Theterms != and <> arealsoequivalentcomparisonsprovidedforcompatibility.SeeComparisonTerms.
Ifacomparisontermismissingfromtheclause,returns MISSING .Ifeitheroperandinacomparisonresultsin NULL
returns NULL .Ifcomparisonoperatorsreturnresultsofdifferenttypes,returns FALSE .
Bydefaultanystringcomparisonsuserawcollation,otherwiseknownasbinarycollation.Thiscollationiscasesensitive.If
youwanttoperformcaseinsensitivecomparisons,youcanfirsttransformastringwith UPPER() or LOWER() functions.
The LIKE operatorenablesyoutodowildcardmatchinginstrings.Youprovideapatterntotherightoftheoperatorswhich
canoptionallycontainwildcardcharactersof % or _ .Thepercentagesign, % ,indicatesanystringofzeroormore
characters.Theunderscore, _ matchesanysinglecharacter.
ComparingNULLandMISSINGvalues

NULL or MISSING valueshavespecialcomparisontermsbecauseweneedtodeterminetypeinformation.Formore

information,seeComparisonTerms.

arithmeticterm performarithmeticmethodswithinanexpression.Thisincludesbasicmathematicaloperationssuch
asaddition,subtraction,multiplication,divisions,andmodulo.Inaddition,anegationoperationwillchangethesignofavalue.
SeeArithmeticOperators.

stringterm ,or || Ifbothoperandsarestrings,the || operatorwillconcatenatethestrings,otherwiseevaluatesto

NULL.

functionname usedtoapplyafunctiontovalues,tovaluesataspecifiedpath,ortovaluesderivedfroma DISTINCT

clause.Forafulllistoffunctions,seeFunctions.

Examples
Givenacustomerorderdocumentwiththefollowinginformation:

{
"type":"contact",
"name":"dave",
"age":45,
"email":"dave@gmail.com",
"children":[
{"name":"aiden","age":17,"gender":"m"},
{"name":"bill","age":2,"gender":"f"}
],
....
}

literalexpr willreturnanyrecordthatmatchestheliteralexpressionprovidedinaquery.Forexample:

SELECTemailFROMcontactsAScontactWHEREcontact.name='dave'

Willreturnemailsfromanycontactswherethecontactnameisdave.Sampleoutputappearsasfollows:

{
"email":"dave@gmail.com"
}

ANY willreturnanyrecordwithoneormoreitemsthatmeettheconditionorexpression.Forexamplethisquerywillreturnall
contactswhohaveoneormorechildrenovertheageof14:

SELECTnameFROMcontactsWHEREANYchild.age>14OVERchildren

Thiswillreturnatoneitemintheresultsetfordavebecauseoneofhischildrenis17.Thesampleoutputisasfollows:

"results":[
{
"name":"dave"
},
....
]

ALL willreturnrecordswithfieldsthatmeetallconditionsorexpressionprovidedinthequery.Forexample,thisqueryisalmost
identicaltotheoneabovewith ANY howeverwesubstituteitfor ALL :

SELECTnameFROMtutorialWHEREALLchild.age>10OVERtutorial.childrenASchild
Thisquerywillscanallcontactsandreturnthenameofanycontactthathaschildrenoverth
eageof10.Exampleoutputforthisqueryisbelow:
{
"name":"ian"
}
Thistellsusthatoutofallofthecontactsonly'ian'haschildrenwhoarebothovertheag
e10.

LIKE willreturncontactsaresimilartoagivenstring.Forexample,togetallcontactswithanemailendingwith@yahoo:

SELECTname,email
FROMtutorial
WHEREemailLIKE'%@yahoo.com'

The%indicatesanycharacterspriorto@canappear.Thiswillreturnoutputsimilartothefollowing:

{
"email":"harry@yahoo.com",
"name":"harry"
},

NOTLIKE istheinverseof LIKE .Itwillreturnitemsthatarenotlikethegivenstring.Forexample,thefollowingclausewill

returnallemailsfromcontactswhichdonotcontain @yahoo :

SELECTname,email
FROMtutorial
WHEREemailNOTLIKE'%@yahoo.com'

Thiswillreturnresultsasfollows:

{
"email":"dave@gmail.com",
"name":"dave"
},

logicalexpr canbeusedtoprovidelogicaloperators,forexampleyoucantestfortwoconditionsatthesametimeina
query:

SELECTnameFROMtutorialWHERELENGTH(children)>0ANDemailLIKE'%@gmail.com'

Thisquerywillscanallcontactsandoutputthenameofanycontactwithmorethanonechildwhoalsohasanemailendingin
@gmail.Exampleoutputfromthisqueryfollows:

{
"name":"dave"
},
....

arithmeticexpr willapplyanarithmeticexpressiontoanynumericalvaluesretrievedaspartofqueryclauses.For
example:

SELECTname,age,age*12ASage_in_months
FROMtutorial
WHEREname='dave'

Thiswillselectthedocumentwherenameisdaveandreturnthename,ageandagetimes12.Exampleoutputappearsas
follows:

{
"age":45,
"age_in_months":540,
"name":"dave"
}

caseexpr willapplyconditionallogictodocuments.Forexamplethefollowingusesa CASE clausetohandledocuments

thatdonothaveanshipdate:

SELECTCASEWHEN`shippedon`ISNOTNULLTHEN`shippedon`ELSE\"notshippedyet\"END
ASshippedFROMorders

Thiswillscanallordersandifanorderhasashippedondate,provideitintheresultset.Ifanorderdoesnothaveashippedon
date,itwillprovidedefaulttextinstead.Sampleoutputforthisqueryisasfollows:

{"shipped":"2013/01/02"},
{"shipped":"2013/01/12"},
{"shipped":"notshippedyet"},
....

SeeAlso
ComparisonTerms
Functions
ArithmeticOperators
ErrorsandResponseCodes

ComparisonTerms
ThefollowingcomparisontermsareavailableinN1QL:

Comparison

Description

Returns

Equalsto

TRUEor
FALSE

==

Equalsto

TRUEor
FALSE

!=

Notequalto

TRUEor
FALSE

<>

Notequalto

TRUEor
FALSE

>

Greaterthan

TRUEor

FALSE
>=

Greaterthanorequalto

TRUEor
FALSE

<

Lessthan

TRUEor
FALSE

<=

Lessthanorequalto

TRUEor
FALSE

LIKE

Matchstringwithwildcardexpression. % forzeroormorewildcards, _

TRUEor
FALSE

tomatchanycharacteratthisplaceinastring
NOTLIKE

InverseofLIKE.ReturnTRUEifstringisnotsimilartogivenstring.

TRUEor
FALSE

ISNULL

FieldhasvalueofNULL.

TRUEor
FALSE

ISNOT
NULL

Fieldhasvalueorismissing.

TRUEor
FALSE

ISMISSING

Novalueforfieldfound.

TRUEor
FALSE

ISNOT
MISSING

ValueforfieldfoundorvalueisNULL.

TRUEor
FALSE

ISVALUED

Valueforfieldfound.ValueisneithermissingnorNULL

TRUEor
FALSE

ISNOT
VALUED

Valueforfieldnotfound.ValueisNULL.

TRUEor
FALSE

ArithmeticOperators
ThefollowingarethearithmeticoperationsinN1QL.Theseoperatorsonlyfunctiononnumericvalues.Ifeitheroperandisnon
numeric,andexpressionwillevaluatetoNULL.

Operator

Description

Additems

Subtractrightvaluefromleft

Multiplyvalues

Divideleftvaluebyright

Modulo.Dividleftvaluebyright,returntheremainder

value

Negatevalue

OperatorsandOperatorPrecedence
ThefollowingoperatorsareavailableinN1QL.Thelistthatfollowsisalsointheorderofprecedencewheretheitemslistedabove
othershaveprecedenceoverthem:

CASE|WHEN|THEN|ELSE|END
.
[]

*/%
+
ISNULL|ISMISSING|ISVALUED
ISNOTNULL|ISNOTMISSING|ISNOTVALUED
LIKE
< , > , <= ,and =>
=
NOT
AND
OR
Youcanalsouseparenthesistocombineexpressionsandoperatorsandtheparenthesishavethehighestprecedence.Ifyouuse
parenthesistogroupoperatorsandexpressions,theseitemswillbeevaluatedfirstandthentheresultwillthenbeusedinanyother
operations.

Functions

N1QLprovidesseveralbuiltinfunctionsforperformingcalculationsondata.Youcanfindbothaggregateandscalarfunctions.
Aggregatefunctionstakemultiplevaluesfromdocuments,performcalculationsandreturnasinglevalueastheresult.Scalar
functionstakeasingleiteminaresultsetandreturnsasinglevalue.Allfunctionnamesarecaseinsensitive.
AggregatefunctionsincludeSUM,AVG,COUNT,MIN,MAXandARRAY_AGG.AggregatefunctionscanonlybeusedinSELECT,
HAVING,andORDERBYclauses.Whenaggregatefunctionsareusedinexpressionsintheseclauses,thequerywilloperateasan
aggregatequery.Aggregatefunctionstakeoneargument,thevalueoverwhichtocomputetheaggregatefunction.TheCOUNT
functioncanalsotakeorpath.asitsargument.

AggregateFunctions
YoucanuseaggregatefunctionsinSELECT,HAVINGandORDERBYclauses.Whenyouuseanaggregatefunctioninaclause
withthesecommands,thequerywillactasanaggregatequery.

Function

Description

Returns

COUNT(expr)

Returnsthenumberitemsinaresultset

0orpositiveinteger

MIN(expr)

Returnsminimumvalueofallvaluesina
resultset.ThisisthefirstnonNULL,non
MISSINGvaluethatwouldresultfroman
ORDERBY

0orpositiveinteger,
NULLifnononNULL,
nonMISSINGitemsin
resultset

MAX(expr)

Returnsmaximumvalueofallvaluesina
resultset.ThisisthelastnonNULL,non
MISSINGvaluethatwouldresultfroman
ORDERBY

0orpositiveinteger

AVG(expr)

Returnsaveragevalueofallvaluesina
resultset.Nonnumericvaluesinaresult
setareignored.

Integer

SUM(expr)

Returnssumofallnumericvaluesina
resultset.Nonnumericvaluesinaresult
setareignored

Integer

ARRAY_AGG(expr)

Evaluatetheexpressionforeach
memberofthegroupandreturnanarray
containingthesevalues

Array

Example

ScalarFunctions
Thesefunctionswillreturnasinglevaluebasedontheitemsinaresultset.ThefollowingarescalarfunctionsinN1QL:

Function

Description

Returns

BASE64_VALUE(value)

Returnthevalueencodedinbase64.
canbeusedonworkwithnonJSON
valuesstoredinthebucket.

value

CEIL(value)

Ifnumericvalues,returnthesmallest
integernolessthanthisvalue.
OtherwiseNULL

NULLor
integer

DATE_PART(field,
source)

Retrievessubfieldssuchasyearor
hourfromdate/timevalues.The
sourcemustbeavalueexpressionof
typetimestamportime

value

FIRSTNUM(expr1,expr2,
)

ReturnsthefirstnonNULL,non
MISSING,nonNaN,noninfinite
numericvalue

NULLor
integer

FLOOR(value)

Ifnumericvalues,returnthesmallest
integernolessthanthisvalue.
OtherwiseNULL

NULLor
integer

GREATEST(expr,expr,
.)

Returnsgreatestvaluefromall
expressionsprovided.Otherwise
NULLifvaluesNULLorMISSING

value

IFINF(expr1,expr2,)

returnsthefirstnoninfinitevalue(+or
)

value

IFMISSING(expr,expr,
.)

ReturnsthefirstnonMISSINGvalue

value

IFMISSINGORNULL(expr,
expr,.)

ReturnsthefirstnonMISSING,non
NULLvalue

value

IFNAN(expr1,expr2,)

ReturnsthefirstnonNaNvalue

value

IFNANORINF(expr1,
expr2,)

returnsthefirstnonNaN,noninfinite
value

value

IFNEGINF(expr1,expr2,
)

Returnsthefirstnoninfinitevalue

value

Example

IFNULL(expr,expr,.)

ReturnsthefirstnonNULLvalue

value

IFPOSINF(expr1,expr2,
)

Returnsthefirstpositivenoninfinite
value

value

LEAST(expr,expr,)

ReturnsthesmallestnonNULL,non
MISSINGVALUEafterevaluatingall
expressions.IfallvaluesareNULLor
MISSING,returnsNULL

valueor
NULL

LENGTH(expr)

Returnsthelengthofthevalueafter
evaluatingtheexpression.Ifstring,
lengthofstring.Forarrays,lengthof
array.Forobjectsreturnsthenumber
ofpairsinobject.Forallothersreturns
NULL

valueor
NULL

LOWER(expr)

Ifexprisastring,returnsstringinall
lowercase,otherwiseNULL

stringor
NULL

LTRIM(expr,charset)

Removethelongeststringcontaining
thecharactersin charset fromstart

stringor
NULL

ofstring.
META()

Returnsmetadataforthedocument

value

MISSINGIF(value1,
value2)

Ifvalue1equalsvalue2return
MISSING,otherwisevalue1

value

NANIF(value1,value2)

Ifvalue1equalsvalue2,returnNaN,
otherwisevalue1

value1
orNaN

NEGINFIF(value1,
value2)

Ifvalue1equalsvalue2,return
negativeinfinity,otherwisevalue1

value1
or
infinity

NOW_STR

Returnscurrentdateandtimeasa
Stringvalue

value

NULLIF(value1,value2)

Ifvaluel1equalsvalue2,returnNULL,
otherwisevalue1.

value1
orNULL

POSINFIF(value1,
value2)

Ifvalue1equalsvalue2,returnpositive
infinity,otherwisevalue1

value1
or
+infinity

ROUND(value)

Ifvalueisnumeric,roundtonearest
integer,otherwiseNULL.Functional
equivalentof ROUND(value,0)

integer
orNULL

length(orders.items)

ROUND(value,digits)

Ifdigitsanintegerandvaluenumeric,
roundsthevalueuptothenumberof
digits.OtherwisereturnsNULL

integer
orNULL

RTRIM(expr,charset)

Removethelongeststringcontaining
onlythecharactersinthespecified
charactersetstartingattheend

stringor
NULL

SUBSTR(value,position)

Forvalueofstringandposition
numeric,returnssubstringfrom
positiontoendofstring.String
positionstartsat1.Ifposition0,starts
atposition1nonetheless.Ifnegative
position,charactersarecountedfrom
theendofstring.Otherwisereturns
NULL.

stringor
NULL

SUBSTR(value,position,
length)

Iflengthispositiveinteger,returns
substringstartingatpositionupto
lengthcharacters.OtherwiseNULL

stringor
NULL

TRIM(expr,charset)

Functionalequivalentof
LTRIM(RTRIM(expr,charset))

stringor
NULL

TRUNC(value)

Ifnumericvalue,truncatestowards
zero.Functionalequivalentof
TRUNC(value,0).Otherwisereturns
NULL

integer
orNULL

TRUNC(value,digits)

Ifdigitsanintegerandvaluenumeric,
truncatesvaluetothespecificnumber
ofdigits.OtherwisereturnsNULL

integer
orNULL

UPPER(expr)

Ifexprastring,returnitinall
uppercaseletters.OtherwiseNULL

stringor
NULL

VALUE()

Returnsthefullvaluefortheitemin
thecurrentcontext

valueor
NULL

ReservedWords

Thefollowingkeywordsarereservedandcannotbeusedasidentifiers.Allkeywordsarecaseinsensitive.
TherewillbemorereservedwordsinthefuturetosupportDDL,DML,compoundstatements,andothers.Toensurethatanidentifier
doesnotconflictwithafuturereservedword,youcanescapetheidentifierwithbackticks.

ALL
ALTER
AND
ANY
ARRAY
AS
ASC
BETWEEN
BUCKET
BY
CASE
CAST
COLLATE
CREATE
DATABASE
DELETE
DESC
DISTINCT
DROP
EACH
ELSE
END
EXCEPT
EXISTS
EXPLAIN
FALSE
FIRST
FROM
GROUP
HAVING
IF
IN
INDEX
INLINE
INSERT
INTERSECT
INTO
IS
JOIN
LIKE
LIMIT
MISSING
NOT

NULL
OFFSET
ON
OR
ORDER
OVER
PATH
POOL
PRIMARY
SELECT
THEN
TRUE
UNION
UNIQUE
UPDATE
USING
VALUED
VIEW
WHEN
WHERE

ReleaseNotes
ThefollowingsectionsprovidereleasenotesforindividualversionsofCouchbaseQueryLanguage(N1QL).

ReleaseNotesforCouchbaseQueryLanguageDeveloperPreview2(November
2013)
ThisistheseconddeveloperprevieweditionofCouchbaseQueryLanguage
NewfeaturesinDP2:

Introducingdate/timefeaturesinthisrelease.SpecificallytwonewfunctionsDATE_PARTand
NOW_STRhavebeenadded.Wewilllikelyexpandcapabilitiesinthisareainsubsequentreleases.
PerformanceImprovements:Betteruseofindexes.Theseareinternalimprovementsintheengine,
forexample,queriescoveredbyindexcaneliminatetheFetchoperatorfindbyidqueriesneednot
scantheindexatallMINchangedtouseindex.
MinorsyntaximprovementsExample,ASkeywordisnowoptional

Stabilityvariousbugfixestohelpimprovethestabilityofqueryengine
FixesinDP2:
Addinitialdateandtimefeatures
Issues:MB9325(http://www.couchbase.com/issues/browse/MB9325)
QueriescoveredbyindexnowavoidtheFETCHoperator
Issues:MB9189(http://www.couchbase.com/issues/browse/MB9189)
Findbyidqueriesnowoptimizedtonotscananindexatall
Issues:MB9187(http://www.couchbase.com/issues/browse/MB9187)
MakeASkeywordoptional
Issues:MB9138(http://www.couchbase.com/issues/browse/MB9138)
MINnowoptimizedtouseindex
Issues:MB9060(http://www.couchbase.com/issues/browse/MB9060)
DISTINCTbehavedunexpectedlywhenusedincombinationwiththeGROUPBYclause.Thisisnowfixed.
Issues:MB9206(http://www.couchbase.com/issues/browse/MB9206)
MakeINoptionalinOVER..INclauses
Issues:MB9136(http://www.couchbase.com/issues/browse/MB9136)
KnownIssuesinDP2:
ThisisaDeveloperPreviewandthisreleaseisnotmeanttobeusedinProduction.

ReleaseNotesforCouchbaseQueryLanguageDeveloperPreview1(September
2013)
ThisisthefirstdeveloperprevieweditionofCouchbaseQueryLanguage