변환(집계)

이 페이지의 내용

정의

호환성
구문
행동
예시

정의

$convert: 값을 지정된 유형으로 변환합니다.

호환성

다음 환경에서 호스팅되는 배포에 $convert 사용할 수 있습니다.

MongoDB Atlas: 클라우드에서의 MongoDB 배포를 위한 완전 관리형 서비스

MongoDB Enterprise: MongoDB의 구독 기반 자체 관리 버전
MongoDB Community: MongoDB의 소스 사용 가능 무료 자체 관리 버전

구문

버전 8.0에서 변경되었습니다.

{
   $convert:
      {
         input: <expression>,
         to: <type expression> || {
            type: <type expression>,
            subtype: <int>
         },
         format: <string>,
         onError: <expression>,
         onNull: <expression>
      }
}

$convert는 다음 필드가 포함된 문서를 사용합니다.

필드

필요성

설명

input

필수 사항

인수는 유효한 모든 표현식일 수 있습니다. 표현식에 대한 자세한 내용은 표현식 연산자를 참조하세요.

to

필수 사항

input 표현식을 변환할 유형을 지정합니다. to를 다음 값 중 하나로 설정할 수 있습니다.

대상 유형에 대한 문자열 또는 숫자 식별자입니다. to.type을 참조하세요.
to.type 및 to.subtype 필드를 포함하는 객체입니다. 이 형식을 사용하여 BinData로 변환하고 BinData 하위 유형을 지정하세요.

to.type

to를 객체로 지정하는 경우에 필요합니다.

인수는 다음 숫자 또는 문자열 식별자 중 하나로 해석되는 모든 유효한 표현식일 수 있습니다.

문자열 식별자	숫자 식별자	참고 사항
"double"	1	double로 변환하는 방법에 대한 자세한 내용은 Double로 변환하기를 참조하세요.
"문자열"	2	문자열로 변환하는 방법에 대한 자세한 내용은 문자열로 변환을 참조하세요.
"binData"	5	binData로 변환하는 방법에 대한 자세한 내용은 BinData로 변환하기를 참조하세요.
"objectId"	7	objectId로 변환하는 방법에 대한 자세한 내용은 ObjectId로 변환을 참조하세요.
"bool"	8	부울로 변환하는 방법에 대한 자세한 내용은 부울로 변환하기를 참조하세요.
'날짜'	9	날짜로 변환하는 방법에 대한 자세한 내용은 날짜로 변환을 참조하세요.
"in"	16	정수로 변환하는 방법에 대한 자세한 내용은 정수로 변환하기를 참조하세요.
"long"	18	Long으로 변환하는 것에 대한 자세한 내용은 Long으로 변환을 참조하세요.
"십진수"	19	10진수로 변환하는 방법에 대한 자세한 내용은 10진수로 변환을 참조하세요.

to.subtype

옵션

to.type이 binData인 경우 to.subtype은 변환할 binData 하위 유형을 지정합니다. to.subtype에 대해 다음 값 중 하나를 지정할 수 있습니다.

번호	설명
0	일반 바이너리 하위 유형
1	함수 데이터
2	바이너리(이전)
3	UUID(이전)
4	UUID
5	MD5
6	암호화된 BSON 값
7	압축된 Time Series 데이터 버전 5.2에 추가되었습니다.
8	키나 시크릿과 같은 민감한 데이터. MongoDB는 하위 유형이 8인 바이너리 데이터에 대한 리터럴 값을 기록하지 않습니다. 대신 자리 표시자 값 `###` 을 기록합니다.
9	벡터 데이터는 동일한 유형의 숫자가 밀집되어 있는 배열입니다.
128	사용자 지정 데이터

기본값: 0(일반 바이너리 하위 유형)

format

binData로 변환하거나 binData에서 변환할 때 필요합니다.

입력 또는 출력의 binData 형식을 지정합니다. 다음 값 중 하나일 수 있습니다.

base64
base64url
utf8
hex
uuid

format이 uuid인 경우 to.subtype은 4여야 합니다.

onError

옵션

변환 중 오류가 발생했을 때 반환할 값입니다. 여기에는 지원되지 않는 유형 변환이 포함됩니다. 인수는 유효한 모든 표현식일 수 있습니다.

지정하지 않으면 오류 발생 시 작업에 오류가 발생하고 중지됩니다.

onNull

옵션

input이 null이거나 누락된 경우 반환할 값입니다. 인수는 유효한 표현식일 수 있습니다.

미지정 시 $convert는 input이 null이거나 누락된 경우 null을 반환합니다.

$convert 이외에도 MongoDB는 기본 'onError'와 'onNull' 동작이 허용되는 경우 다음과 같은 집계 연산자를 축약형으로 제공합니다.

행동

BinData로 변환

문자열은 binData로만 변환할 수 있습니다. 다른 모든 입력 유형은 오류가 발생합니다.

다음 binData로의 변환 예시를 참조하세요.

예시

결과

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 0
   },
   format: "base64"
}

Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: "binData",
   format: "base64"
}

Binary.createFromBase64('hn3uUsMxSE6S0cVkebjmfg==', 0)

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: {
      type: "binData",
      subtype: 0
   },
   format: "base64",
}

Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'
in $convert with no onError value: Input is not a valid base64
string.

{
   input: "hn3uUsMxSE6S0cVkebjmfg==",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "base64"
}

Failed to parse BinData 'hn3uUsMxSE6S0cVkebjmfg==' in $convert
with no onError value: Input is not a valid base64 string.

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "uuid"
}

UUID('867dee52-c331-484e-92d1-c56479b8e67e')

{
   input: "äöäöä",
   to: {
      type: "binData",
      subtype: 4
   },
   format: "uuid"
}

Failed to parse BinData 'äöäöä' in $convert with no onError
value: Input is not a valid UUID string.

{
   input: "867dee52-c331-484e-92d1-c56479b8e67e",
   to: { type: "binData" },
   format: "uuid"
}

Failed to parse BinData '867dee52-c331-484e-92d1-c56479b8e67e'
in $convert with no onError value: Only the UUID subtype (4)
is allowed with the 'uuid' format.

{
   input: 123,
   to: { type: "binData", subtype: 0 }
}

Unsupported conversion from int to binData in $convert with no onError value

부울로 변환

다음 표에는 더블로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
배열	true를 반환합니다
이진 데이터	true를 반환합니다
부울	아니요. 부울 값을 반환합니다.
코드	true를 반환합니다
날짜	true를 반환합니다
10진수	Returns true if not zero Return false if zero
Double	Returns true if not zero Return false if zero
Integer	Returns true if not zero Return false if zero
JavaScript	true를 반환합니다
Long	Returns true if not zero Return false if zero
최대 키	true를 반환합니다
최소 키	true를 반환합니다
Null	`onNull` 옵션에 지정된 값을 반환합니다. 기본적으로 null을 반환합니다.
객체	true를 반환합니다
ObjectId	true를 반환합니다
정규 표현식	true를 반환합니다
문자열	true를 반환합니다
타임스탬프	true를 반환합니다

MongoDB의 데이터 유형에 대해 자세히 알아보려면 BSON types를 참조하세요.

다음 표에는 더블로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "bool" }

true

{ input: false, to: "bool" }

거짓

{ input: 1.99999, to: "bool" }

true

{ input: Decimal128( "5" ), to: "bool" }

true

{ input: Decimal128( "0" ), to: "bool" }

거짓

{ input: 100, to: "bool" }

true

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "bool"
}

true

{ input: "hello", to: "bool" }

true

{ input: "false", to: "bool" }

true

{ input: "", to: "bool" }

true

{ input: null, to: "bool" }

null

팁

다음도 참조하세요.

$toBool

정수로 변환

다음 표에는 정수로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns `0` for `false`. Returns `1` for `true`.
Double	잘린 값을 반환합니다. 잘린 double 값은 정수의 최소값과 최대값 내에 속해야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 double 값은 변환할 수 없습니다.
10진수	잘린 값을 반환합니다. 잘린 10진수 값은 정수의 허용 범위 내에 있어야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 소숫값은 변환할 수 없습니다.
Integer	아니요. 정수 값을 반환합니다.
Long	긴 값을 정수로 반환합니다. long 값은 정수의 최소값과 최대값 내에 있어야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 Long 값은 변환할 수 없습니다.
문자열	문자열의 숫자 값을 정수로 반환합니다. 문자열 값은 기본 _10진수여야 하고(예: `"-5"`, `"123456"`) 최솟값과 최댓값 범위 내에 있어야 합니다. 부동소수점, 십진수, ₁₀이 아닌 밑수의 문자열 값(예: `"-5.0"`, `"0x6400"`) 또는 정수의 최소값과 최대값을 벗어나는 값은 변환할 수 없습니다.

다음 표에는 정수로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "int" }

{ input: false, to: "int" }

{ input: 1.99999, to: "int" }

{ input: Decimal128( "5.5000" ), to: "int" }

{
   input: Decimal128( "9223372036000.000" ),
   to: "int"
}

오류

{ input: Long( "5000" ), to: "int" }

5000

{ input: Long( "922337203600" ), to: "int" }

오류

{ input: "-2", to: "int" }

-2

{ input: "2.5", to: "int" }

오류

{ input: null, to: "int" }

null

팁

다음도 참조하세요.

$toInt 연산자를 사용하세요.

10진수로 변환

다음 표에는 10진수로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns `Decimal128( "0" )` for `false`. Returns `Decimal128( "1" )` for `true`.
Double	double 값을 10진수로 반환합니다.
10진수	아니요. 소수를 반환합니다.
Integer	int 값을 10진수로 반환합니다.
Long	Long 값을 10진수로 반환합니다.
문자열	문자열의 숫자 값을 10진수로 반환합니다. 문자열 값은 _10을 기본으로 하는 숫자 값이어야 합니다(예 `"-5.5"`, `"123456"`). 기본 _10이 아닌 숫자의 문자열 값은 변환할 수 없습니다(예 `"0x6400"`)
날짜	날짜 값에 해당하는 epoch 이후의 밀리초 수를 반환합니다.

다음 표에는 10진수로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "decimal" }

Decimal128("1")

{ input: false, to: "decimal" }

Decimal128("0")

{ input: 2.5, to: "decimal" }

Decimal128( "2.50000000000000" )

{ input: Int32( 5 ), to: "decimal" }

Decimal128("5")

{ input: Long( 10000 ), to: "decimal" }

Decimal128("10000")

{ input: "-5.5", to: "decimal" }

Decimal128("-5.5")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "decimal"
}

Decimal128("1522039108044")

팁

다음도 참조하세요.

$toDecimal

double로 변환

다음 표에는 double로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns NumberDouble(0) for `false`. Returns NumberDouble(1) for `true`.
Double	아니요. double 값을 반환합니다.
10진수	10진수 값을 double로 반환합니다. 10진수 값은 double의 최소값과 최대값 내에 속해야 합니다. 값이 최소 double 값보다 작거나 최대 double 값보다 큰 10진수 값은 변환할 수 없습니다.
Integer	int 값을 double로 반환합니다.
Long	긴 값을 double로 반환합니다.
문자열	문자열의 숫자 값을 double로 반환합니다. 문자열 값은 _10진수 숫자 값 (예: `"-5.5"` `"123456"`) 이어야 하며, double의 최소값과 최대값 내에 속합니다. _10진수가 아닌 숫자 형태의 문자열 값(예: `"0x6400"`) 이나 double의 최소값과 최대값을 벗어나는 값은 변환할 수 없습니다.
날짜	날짜 값에 해당하는 epoch 이후의 밀리초 수를 반환합니다.

다음 표에는 double로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "double" }

{ input: false, to: "double" }

{ input: 2.5, to: "double" }

2.5

{ input: Int32( 5 ), to: "double" }

{ input: Long( "10000" ), to: "double" }

10000

{ input: "-5.5", to: "double" }

-5.5

{ input: "5e10", to: "double" }

50000000000

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "double"
}

1522039108044

팁

다음도 참조하세요.

$toDouble

길게 변환

다음 표에는 로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
부울	Returns `0` for `false`. Returns `1` for `true`.
Double	잘린 값을 반환합니다. 잘린 double 값은 정수의 최소값과 최대값 내에 속해야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 double 값은 변환할 수 없습니다.
10진수	잘린 값을 반환합니다. 잘린 10진수 값은 정수의 허용 범위 내에 있어야 합니다. 최소 정수 값보다 작거나 최대 정수 값보다 큰 더블 값은 변환할 수 없습니다.
Integer	int 값을 길이로 반환합니다.
Long	아니요. 긴 값을 반환합니다.
문자열	문자열의 숫자 값을 반환합니다. 문자열 값은 기본 ₁₀진수 길이여야 하고(예: `"-5"`, `"123456"`) 최솟값과 최댓값 범위 내에 있어야 합니다. 부동소수점, 십진수, ₁₀이 아닌 밑수의 문자열 값(예: `"-5.0"`, `"0x6400"`) 또는 long의 최소값과 최대값을 벗어나는 값은 변환할 수 없습니다.
날짜	Date를 epoch 이후의 밀리초 수로 변환합니다.

다음 표에는 더블로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "long" }

Long("1")

{ input: false, to: "long"  }

Long("0")

{ input: 2.5, to: "long"  }

Long("2")

{ input: Decimal128( "5.5000" ), to: "long" }

Long("5")

{
   input: Decimal128( "9223372036854775808.0" ),
   to: "long"
}

오류

{ input: Int32( 8 ), to: "long" }

Long("8")

{
   input: ISODate( "2018-03-26T04:38:28.044Z" ),
   to: "long"
}

Long("1522039108044")

{ input: "-2", to: "long" }

Long("-2")

{ input: "2.5", to: "long" }

오류

{ input: null, to: "long" }

null

팁

다음도 참조하세요.

$toLong

날짜로 변환

다음 표에는 날짜로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
Double	잘린 double 값이 나타내는 밀리초 수에 해당하는 날짜를 반환합니다. 양수는 1970년 1월 1일 이후의 밀리초 수에 해당합니다. 음수는 1970년 1월 1일 이전의 밀리초 수에 해당합니다.
10진수	잘린 10진수 값이 나타내는 밀리초 수에 해당하는 날짜를 반환합니다. 양수는 1970년 1월 1일 이후의 밀리초 수에 해당합니다. 음수는 1970년 1월 1일 이전의 밀리초 수에 해당합니다.
Long	long 값이 나타내는 밀리초 수에 해당하는 날짜를 반환합니다. 양수는 1970년 1월 1일 이후의 밀리초 수에 해당합니다. 음수는 1970년 1월 1일 이전의 밀리초 수에 해당합니다.
문자열	날짜 문자열에 해당하는 날짜를 반환합니다. 문자열은 다음과 같이 유효한 날짜 문자열이어야 합니다: "2018-03-03" "2018-03-03T12:00:00Z" "2018-03-03T12:00:00+0500"
ObjectId	ObjectId의 타임스탬프에 해당하는 날짜를 반환합니다.
타임스탬프	타임스탬프에 해당하는 날짜를 반환합니다.

다음 표에는 날짜로의 몇 가지 변환 예가 나열되어 있습니다.

예시

결과

{
   input: 120000000000.5,
   to: "date"
}

ISODate("1973-10-20T21:20:00.000Z")

{
   input: Decimal128( "1253372036000.50" ),
   to: "date"
}

ISODate("2009-09-19T14:53:56.000Z")

{
   input: Long( "1100000000000" ),
   to: "date
}

ISODate("2004-11-09T11:33:20.000Z")

{
   input:  Long( "-1100000000000" ),
   to: "date"
}

ISODate("1935-02-22T12:26:40.000Z")

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "date"
}

ISODate("2018-03-27T04:08:58.000Z")

{ input:  "2018-03-03", to: "date" }

ISODate("2018-03-03T00:00:00.000Z")

{
   input: "2018-03-20 11:00:06 +0500",
   to: "date"
}

ISODate("2018-03-20T06:00:06.000Z")

{ input: "Friday", to: "date" }

오류

{
   input: Timestamp( { t: 1637688118, i: 1 } ),
   to: "date"
}

ISODate("2021-11-23T17:21:58.000Z")

팁

다음도 참조하세요.

$toDate 연산자
$dateFromString

ObjectId로 변환

다음 표에는 ObjectId로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
문자열	길이 24의 16진수 문자열에 대한 ObjectId를 반환합니다. 길이가 24인 16진수 문자열이 아닌 문자열 값은 변환할 수 없습니다.

다음 표에는 날짜로의 몇 가지 변환 예가 나열되어 있습니다.

예시

결과

{
   input: "5ab9cbfa31c2ab715d42129e",
   to: "objectId"
}

ObjectId("5ab9cbfa31c2ab715d42129e")

{
   input: "5ab9cbfa31c2ab715d42129",
   to: "objectId"
}

오류

팁

다음도 참조하세요.

$toObjectId 연산자를 사용하세요.

문자열로 변환

다음 표에는 문자열로 변환할 수 있는 입력 유형이 나열되어 있습니다.

입력 유형	행동
BinData	바이너리 데이터 값을 문자열로 반환합니다.
부울	부울 값을 문자열로 반환합니다.
Double	double 값을 문자열로 반환합니다.
10진수	십진수 값을 문자열로 반환합니다.
Integer	정수 값을 문자열로 반환합니다.
Long	긴 값을 문자열로 반환합니다.
ObjectId	ObjectId 값을 16진수 문자열로 반환합니다...
문자열	아니요. 문자열 값을 반환합니다.
날짜	날짜를 문자열로 반환합니다.

다음 표에는 문자열로 변환하는 몇 가지 예가 나와 있습니다:

예시

결과

{ input: true, to: "string" }

"true"

{ input: false, to: "string" }

"false"

{ input: 2.5, to: "string" }

"2.5"

{ input: Int32( 2 ), to: "string" }

"2"

{ input:  Long( 1000 ), to: "string" }

"1000"

{
   input: ObjectId( "5ab9c3da31c2ab715d421285" ),
   to: "string"
}

"5ab9c3da31c2ab715d421285"

{
   input:  ISODate( "2018-03-27T16:58:51.538Z" ),
   to: "string"
}

"2018-03-27T16:58:51.538Z"

{
   input: BinData(4, "hn3f"),
   to: "string",
   format: "base64"
}

'hn3f'

팁

다음도 참조하세요.

$toString 연산자
$dateToString

예시

다음 문서를 사용하여 컬렉션 orders를 생성합니다.

db.orders.insertMany( [
   { _id: 1, item: "apple", qty: 5, price: 10 },
   { _id: 2, item: "pie", qty: 10, price: Decimal128("20.0") },
   { _id: 3, item: "ice cream", qty: 2, price: "4.99" },
   { _id: 4, item: "almonds" },
   { _id: 5, item: "bananas", qty: 5000000000, price: Decimal128("1.25") }
] )

orders 컬렉션에서의 다음 집계 연산은 price를 10진수로 변환합니다.

// Define stage to add convertedPrice and convertedQty fields with
//    the converted price and qty values.
// If price or qty values are missing, the conversion returns a
//    value of decimal value or int value of 0.
// If price or qty values cannot be converted, the conversion returns
//    a string
priceQtyConversionStage = {
   $addFields: {
      convertedPrice: { $convert:
         {
            input: "$price",
            to: "decimal",
            onError: "Error",
            onNull: Decimal128("0")
         } },
      convertedQty: { $convert:
         {
            input: "$qty",
            to: "int",
            onError:{ $concat:
               [
                  "Could not convert ",
                  { $toString:"$qty" },
                  " to type integer."
               ]
            },
         onNull: Int32("0")
      } },
   }
};
totalPriceCalculationStage = {
   $project: { totalPrice: {
     $switch: {
        branches: [
          { case:
             { $eq: [ { $type: "$convertedPrice" }, "string" ] },
             then: "NaN"
          },
          { case:
             { $eq: [ { $type: "$convertedQty" }, "string" ] },
             then: "NaN"
          },
        ],
        default: { $multiply: [ "$convertedPrice", "$convertedQty" ] }
     }
} } };
db.orders.aggregate( [
   priceQtyConversionStage,
   totalPriceCalculationStage
])

이 작업은 다음 문서를 반환합니다.

{ _id: 1, totalPrice: Decimal128("50") },
{ _id: 2, totalPrice: Decimal128("200.0") },
{ _id: 3, totalPrice: Decimal128("9.98") },
{ _id: 4, totalPrice: Decimal128("0") },
{ _id: 5, totalPrice: 'NaN' }

참고

이 예시에서는 mongosh를 사용합니다. 레거시 mongo 셸에서는 기본 유형이 다릅니다.

돌아가기

$cond

$cos